feat(macros/AvailableInWorkers): support more distinct cases

[teoli2003]

Summary

We have the {{AvailableInWorkers}} macro that adds a message indicating a feature is available in web workers.

It was created a long time ago (when workers were added to the web platform) and supports only two cases:

• all web workers (and Window) support the feature;
• all web workers support the feature, but service workers (and Window).

Over the years, many other cases were added. I've found cases where a given feature is supported:

• only in a DedicatedWorker (and in Window)
• only in a DedicatedWorker (even not Window)
• only in a ServiceWorker (even not Window)
• only in ServiceWorker (and in Window)

This PR adds these few cases.

Fixes #10009

Problem

We have content cases where no adequate message can be displayed: E.g., mdn/content#30191 (comment). Many (read: ~50) occurrences will use it (either the macro call is missing or the text shown is not correct)

This PR fixes it by allowing more strings in parameters.

Solution

The macro now tests more argument values and sets the correct text for each of them.

In the long term, we may want to read this info from w3c/webref, but there are many more global scopes (Worklets, JsonLD, RTCIdentityProvider, InterestGroupScriptRunnerGlobalScope…), so it would mean renaming this macro (for the least). A bit overkill for the current needs.

Screenshots

I've added the macros in a file with the different messages:

And checked the result:

---

How did you test this change?

Manually tested (see screenshot)

[teoli2003]

cc/ @bsmth

[bsmth]

Oh super, that's pretty cool, tnx. Would be interesting to get feedback from other there, but looks good to me 👍

[teoli2003]

A point that I forgot to mention: the macro stays compatible with what exists today; it can be merged without simultaneous changes to mdn/content.

[skyclouds2001]

maybe we could add one more case, for example, using the notserviceonly to suggest that all web workers support the feature, but service workers (event not Window)

a possible example is FileReaderSync interface

[teoli2003]

Good catch! I added it under the name notservicenotwindow (I found notserviceonly not clear).

With the new structure, it is quick to add new cases.

[bsmth]

maybe we could add one more case, for example, using the notserviceonly to suggest that all web workers support the feature, but service workers (event not Window)

a possible example is FileReaderSync interface

I was going to tag you in a related PR to let you know about these changes, but you're already on it :)

[bsmth]

Thanks a lot, going to leave a +1 on this. Will not merge yet in case anyone else has comments or feedback. 👍🏻

[yin1999]

Those strings are really similar, is it possible that we can set up some template for them?

Note, we need to localize both plain texts ("This feature is available in ${{place holder}}", ...) and link texts ("Web Workers", "Service Workers", etc. For zh-CN and zh-TW locales, we will remove the tailing "s")

[caugner]

Would it make sense to have a more generic/systematic interface?

{{AvailableInWorkers("only", "dedicated,window"}}
{{AvailableInWorkers("only", "dedicated"}}
{{AvailableInWorkers("except", "service"}}
{{AvailableInWorkers("except", "service,window"}}
{{AvailableInWorkers("only", "service,window"}}
{{AvailableInWorkers("only", "service"}}

[caugner]

Alternatively, I would prefer to have the keys a bit more verbose:

only_dedicated_and_window
only_dedicated
except_service
except_service_and_window
only_service_and_window
only_service

[teoli2003]

I apply @caugner proposal, which is better:

• only_dedicated_and_window
• only_dedicated
• except_service
• except_service_and_window
• only_service_and_window
• only_service

It isn't compatible with the current parameter (notservice), but this can be fixed quickly (a find and replace.

Internally, I kept the complete sentences (not following yin1999 request) as 1) it is a non-trivial change, 2) we will need to be redone anyway when we will do a more generic macro ({{Available}}) that can handle all cases of the Exposed= WebIDL extended attribute 3) few (if any) extra cases are expected in the mid-term (2023-2024).

[caugner]

@teoli2003 Isn't this the same as only_dedicated?

[teoli2003]

No, there can be a SharedWorker too: https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker

(At least it is my understanding)

[skyclouds2001]

except_service_and_window = DedicatedWorker + SharedWorker
only_dedicated = DedicatedWorker

[caugner]

Thanks for the clarification, so this sounds like except_service_and_window could also be named dedicated_and_shared?

Wouldn't it be easiest to just list the workers in which the feature is available (e.g. dedicated,shared) and display a comma separated list of worker types where the feature is available?

Looking at the screenshots again, I find it confusing that there is "available in Dedicated Web Workers" and "only available in Dedicated Web Workers".

[hamishwillee]

@caugner it sounds like this is hard because we can't easily specify multiple options in a macro. Why don't we just do the same as compat/specs and pull the information from metadata? Then we can make the support explicit:

worker support

• window
• dedicated worker
• shared worker
• service worker

Then {{AvailableInWorkers}} renders some standard text then "Supported in the following types of workers: [list]". If no metadata specified we could assume "all".

Would that be better?

[teoli2003]

We can get the info from w3c/webref. Nevertheless, there is one caveat the website equivalent for {{AvailableInWorker}}: it is more generic as would really be an {{Availability}} macro. There are many more cases: it would tell us if something is available in Worklet (of all kinds), in RTC's Identity provider, …

I think the mid-term solution would be to ditch {{AvailableInWorker}} for an {{Availability}} macro that we can put everywhere (like {{Specifications}} and {{Compat}}). I didn't do this here as this is a much more significant chunk of work (because there are many more cases, and it has to work with additional ones that can appear in the future, and because we need to obtain the w3c/webref key – again not really difficult but a more significant chunk of work).

That's why I wanted a short-term, more effortless solution (once we have the mid-term solution, a script can be run to update all the pages).

From the two proposals from @caugner:

• more explicit text (dedicated_and_shared)
• list of features

I prefer the first one as we don't need to add some parsing (or a loop with many unused cases) to the code. The only caveat is that it won't be compatible with the current arguments (which is why I chose the current keywords), so we need a find and replace PR on the whole MDN once this lands (not difficult).

It is on my todo list to update this PR, hopefully today (but so many things are happening in parallel, so that's not a promise)

[hamishwillee]

FWIW I much prefer my proposal of using metadata. This #10029 (comment) is overly complicated because you're trying to define exceptions.

I'm not sure about "one {{Availability}} macro to rule them all". If we have stuff in metadata I think we can do away with macros altogether at some point.

EDIT PS, though I guess I'd like this in "as is" to never getting agreement :-)

[teoli2003]

In the mid-term, we won't even need metadata as this information is available via w3c/webref, which we already use in some macros. (But that's a significant chunk of work, and we need both some writers to define where and how (=text) to display on the page and non-trivial reviewing of the new macro).

That's why I would prefer this stop-gap first: it is similar to what we do know and doesn't impair the change in the future (a find-and-replace script will be easy to do)

[hamishwillee]

OK. Then how do we get this in!!!

[teoli2003]

What about the following? (The commit c1232e5 implements it):

From:
// 'only_dedicated_and_window': only in DedicatedWorker (and in Window)
// 'only_dedicated': only in DedicatedWorker
// 'except_service': all workers but ServiceWorker (and in Window)
// 'except_service_and_window': all workers but ServiceWorker (and no window)
// 'only_service_and_window': only in ServiceWorker (and in Window)
// 'only_service': only in ServiceWorker
// null: (default) All workers (and Window)

To:
// 'window_and_dedicated': only in DedicatedWorker (and in Window)
// 'dedicated': only in DedicatedWorker
// 'window_and_worker_except_service': all workers but ServiceWorker (and in Window)
// 'worker_except_service': all workers but ServiceWorker (and no window)
// 'window_and_service': only in ServiceWorker (and in Window)
// 'service': only in ServiceWorker
// null: (default) All workers (and Window)

The current {{AvailableInWorker("notservice")}} must be changed to {{AvailableInWorker("worker_except_service")}} (Follow-up mdn/content PR if this one is approved)

[skyclouds2001]

Is it still working in progress?

[caugner]

LGTU (@argl @fiji-flo @caugner), thanks! 🎉