Skip to content

Commit 61466d7

Browse files
authored
New text for guidance on exposing interfaces everywhere (#510)
1 parent 7e13baf commit 61466d7

File tree

1 file changed

+62
-0
lines changed

1 file changed

+62
-0
lines changed

index.bs

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2849,6 +2849,68 @@ because use of {{ScriptProcessorNode}} from the main thread
28492849
frequently resulted in a poor user experience. [[WebAudio]]
28502850
</p>
28512851

2852+
## Only purely computational features should be exposed everywhere ## {#expose-everywhere}
2853+
<!--
2854+
https://github.com/w3ctag/design-principles/issues/509
2855+
https://github.com/whatwg/webidl/issues/468
2856+
https://github.com/w3ctag/design-principles/issues/35
2857+
-->
2858+
2859+
When exposing a feature,
2860+
please consider whether it makes sense
2861+
to expose the feature to all possible environments
2862+
(via the {{Exposed|[Exposed=*]}} annotation
2863+
or including it on all global scope interfaces).
2864+
2865+
Only purely computational features should be exposed everywhere.
2866+
That is,
2867+
they do not perform I/O
2868+
and do not affect the state of the user agent or the user’s device.
2869+
2870+
<p class="example">
2871+
The {{TextEncoder}} interface converts a string to UTF-8 encoded bytes.
2872+
This is a purely computational interface,
2873+
generally useful as a JavaScript language facility,
2874+
so it should be exposed everywhere.
2875+
</p>
2876+
2877+
<p class="example">
2878+
<a attribute spec=html>localStorage</a> affects the state of the user agent, so it should not be exposed everywhere.
2879+
</p>
2880+
2881+
<p class="example">
2882+
Technically, {{console}} could affect the state of the user agent
2883+
(by causing log messages to appear in the developer tools)
2884+
or the user’s device
2885+
(by writing to a log file.)
2886+
But these things are not observable from the running code,
2887+
and the practicality of having {{console}} everywhere outweighs the disadvantages.
2888+
</p>
2889+
2890+
Additionally, anything relying on an event loop
2891+
should not be exposed everywhere.
2892+
Not all global scopes have an event loop.
2893+
2894+
<p class="example">
2895+
The {{AbortSignal/timeout(milliseconds)|timeout}} method of {{AbortSignal}}
2896+
relies on an event loop
2897+
and should not be exposed everywhere.
2898+
The rest of {{AbortSignal}} is purely computational,
2899+
and should be exposed everywhere.
2900+
</p>
2901+
2902+
The {{Exposed|[Exposed=*]}} annotation should also be applied conservatively.
2903+
If a feature is not that useful
2904+
without other features that are not exposed everywhere,
2905+
default to not exposing that feature as well.
2906+
2907+
<p class="example">
2908+
The {{Blob}} interface is purely computational,
2909+
but {{Blob}} objects are primarily used for, or obtained as a result of, I/O.
2910+
By the principle of exposing conservatively,
2911+
Blob should not be exposed everywhere.
2912+
</p>
2913+
28522914
<h3 id="new-data-formats">Add new data formats properly</h3>
28532915

28542916
Always define a corresponding MIME type and extend existing APIs to support this type

0 commit comments

Comments
 (0)