Move WindowOrWorkerGlobalScope features to api.* (_globals folder)

[Elchi3]

This PR illustrates unifying Window and WorkerGlobalScope in a globals.json file and marking worker support in sub features.

The alternate approach is a split, see #11517

Context: #9127

[ddbeck]

I'm still undecided on splitting or lumping here, but I do have thoughts on this:

the schema doesn't like this, it wants these exports in one file per export

Seems to me, since we're doing something quite similar to mixins in this approach, that we could do something similar and avoid changing the schema:

 _globals/
  ├── atob.json
  ├── btoa.json
  ├── caches.json
  └── clearInterval.json

[Elchi3]

That seems a lot better, yes. (although more work).

What do we define as "globals", though? I guess there are more features that qualify outside of WindowOrWorkerGlobalScope?

[foolip]

There are a few additional properties that are on the global object in both window and worker contexts to consider here, namely location, navigator and performance.

location and navigator don't have the same type in both contexts and thus don't have identical IDL definitions for both, so leaving those separate is probably a good idea. But performance I think should be a global api.performance.

There's also the interesting case of close() which exists in both contexts but is not the same:
https://developer.mozilla.org/en-US/docs/Web/API/Window/close
https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/close

Similarly, both have a self property, and while it could be described in the same terms, they are usefully documented separately:
https://developer.mozilla.org/en-US/docs/Web/API/Window/self
https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/self

[foolip]

Oh, performance is actually defined using the WindowOrWorkerGlobalScope mixin:
https://w3c.github.io/hr-time/#the-performance-attribute

[foolip]

What do we define as "globals", though? I guess there are more features that qualify outside of WindowOrWorkerGlobalScope?

Indeed, there are some APIs available only on Window which nevertheless similar to fetch() or performance in how they're used without Window being especially relevant. Candidates:

• alert() and friends
• crypto
• history
• localStorage and sessionStorage
• requestIdleCallback
• speechSynthesis

Some are actually pretty entwined with the main thread, history most obviously so, but it's not super clear how to draw the line here.

I would be happy enough with a guidelines saying that only things available in more than one global scope should be given the globals treatment. An objective rule would at least make it easier on tooling (like mdn-bcd-collector) to map from Web IDL to BCD paths.

[Elchi3]

Seems to me, since we're doing something quite similar to mixins in this approach, that we could do something similar and avoid changing the schema:

 _globals/
  ├── atob.json
  ├── btoa.json
  ├── caches.json
  └── clearInterval.json

Done! Much better

[Elchi3]

I would be happy enough with a guidelines saying that only things available in more than one global scope should be given the globals treatment. An objective rule would at least make it easier on tooling (like mdn-bcd-collector) to map from Web IDL to BCD paths.

Right, it would be good to get a list of "globals" derived from Web IDL syntax.

[teoli2003]

Question: how do we deal with recent global scopes like AudioWorkletGlobalScope ? console is available on it (as it is a namespace), but most other "global" properties/methods like atob not.

[foolip]

Question: how do we deal with recent global scopes like AudioWorkletGlobalScope ? console is available on it (as it is a namespace), but most other "global" properties/methods like atob not.

It's not really because it's a namespace, rather it's because of [Exposed=(Window,Worker,Worklet)] in https://console.spec.whatwg.org/#console-namespace which can also be used for interfaces, for example here:
https://streams.spec.whatwg.org/#rs-class-definition

[foolip]

it would be good to get a list of "globals" derived from Web IDL syntax.

The only way of defining global method or properties using Web IDL is to add stuff to Window, WorkerGlobalScope or another interface representing a global scope. (These use the Global extended attribute and are thus easy to enumerate.)

I would say only methods or properties added to more than one global scope should count. The tricky bit is determining from Web IDL if they are the same, or just share a name. For WindowOrWorkerGlobalScope it can be inferred, but there's no WindowOrWorkerOrWorkletGlobalScope yet. How exactly specs use mixins vs. partials might change over time.

So, even though a rule involving WindowOrWorkerGlobalScope might work now, I think we should rather say that it's a global if it's exposed in two or more globals and it has the same definition (likely spec_url) in both cases. That avoids the two close() methods with exactly the same signature being treated as a global:
https://html.spec.whatwg.org/multipage/window-object.html#dom-window-close
https://html.spec.whatwg.org/multipage/workers.html#dom-dedicatedworkerglobalscope-close

This does require human judgement, but I think in practice it will be possible to infer from the state of Web IDL at any given time, it's just that the rule might have to evolve with changes to specs and Web IDL itself.

Another option I think we should discard:

Simplest possible rule

The simplest we could do is to say that anything exposed on any global object is a global. Unfortunately, this leads to the silly conclusion that window.resizeTo() is a global, when the window is the thing being resized. It's very unlike fetch(), which can be understood without reference to window.

This also wouldn't work for close(), which has the same name but does something different for Window and WorkerGlobalScope. And it makes no sense for the properties of AudioWorkletGlobalScope.

[foolip]

@Elchi3 do you want to change the title of this PR? It's not unifying all of Window and WorkerGlobalScope, but extracting and deduplicating some bits.

[Elchi3]

I've closed #11517. We'd like to go ahead with this PR.

[foolip]

@Elchi3 can you resolve conflicts? Even without conflicts there's probably a risk that something has changed since the PR was created, so how to verify that this isn't accidentally reverting any data?

[Elchi3]

Ah yes, I should probably re-do this entirely.

[Elchi3]

Okay running into difficulties here...

I can't move api.window.crypto to api.crypto because it collides with api.Crypto.
BCD might support this (exports are case-sensitive), but on MDN you have lowercase folders only, so I can't have this folder twice: content/files/en-us/web/api/crypto.

[Elchi3]

I reverted the crypto change. I think we should deal with it in a follow-up.

[saschanaz]

This sounds like a major change at least for code generators, not sure why it didn't even got a minor version up 👀

[Elchi3]

Thanks for your feedback. I released this according to https://github.com/mdn/browser-compat-data#semantic-versioning-policy.

You should expect lower-level namespaces, feature data, and browser data to be added, removed, or modified at any time. That said, we strive to communicate changes and preserve backward compatibility; if you rely on a currently undocumented portion of the package and want SemVer to apply to it, please open an issue.

Like other mixins, WindowOrWorkerGlobalScope was not a protected namespace per this policy. However, I'd like to understand how you consume BCD and what needs to be taken into account for "code generators".

[foolip]

Some adaptation in mdn-bcd-collector will be needed too. The problem is basically how to create a mapping between Web IDL and BCD paths. Previously, assuming mixin flattening, the path for fetch() would have been api.Window.fetch + api.WorkerGlobalScope.fetch. Now it should instead be api.fetch and api.fetch.worker_support.

[Elchi3]

So mixin flattening would have been the preferred approach? I'm a bit puzzled now...

[saschanaz]

Non-breaking rather than preferred, I guess

[foolip]

No, this is exactly the approach I prefer, I'm just saying what changes will be needed in IDL<->BCD mapping.

[queengooborg]

I personally think that this was a significant enough change that a minor bump should have been made, if not a major bump. Consumers have shown concern for when features have moved around or been removed, and I feel that we should help communicate these changes with our version numbers. A change like this was versioned properly according to our guidelines, but maybe we should revise them a little?