Skip to content

Commit 1156f29

Browse files
ptomatomartinthomson
authored andcommitted
New text for guidance on exposing interfaces everywhere (#510)
1 parent 088ebdc commit 1156f29

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
@@ -2886,6 +2886,68 @@ because use of {{ScriptProcessorNode}} from the main thread
28862886
frequently resulted in a poor user experience. [[WebAudio]]
28872887
</p>
28882888

2889+
## Only purely computational features should be exposed everywhere ## {#expose-everywhere}
2890+
<!--
2891+
https://github.com/w3ctag/design-principles/issues/509
2892+
https://github.com/whatwg/webidl/issues/468
2893+
https://github.com/w3ctag/design-principles/issues/35
2894+
-->
2895+
2896+
When exposing a feature,
2897+
please consider whether it makes sense
2898+
to expose the feature to all possible environments
2899+
(via the {{Exposed|[Exposed=*]}} annotation
2900+
or including it on all global scope interfaces).
2901+
2902+
Only purely computational features should be exposed everywhere.
2903+
That is,
2904+
they do not perform I/O
2905+
and do not affect the state of the user agent or the user’s device.
2906+
2907+
<p class="example">
2908+
The {{TextEncoder}} interface converts a string to UTF-8 encoded bytes.
2909+
This is a purely computational interface,
2910+
generally useful as a JavaScript language facility,
2911+
so it should be exposed everywhere.
2912+
</p>
2913+
2914+
<p class="example">
2915+
<a attribute spec=html>localStorage</a> affects the state of the user agent, so it should not be exposed everywhere.
2916+
</p>
2917+
2918+
<p class="example">
2919+
Technically, {{console}} could affect the state of the user agent
2920+
(by causing log messages to appear in the developer tools)
2921+
or the user’s device
2922+
(by writing to a log file.)
2923+
But these things are not observable from the running code,
2924+
and the practicality of having {{console}} everywhere outweighs the disadvantages.
2925+
</p>
2926+
2927+
Additionally, anything relying on an event loop
2928+
should not be exposed everywhere.
2929+
Not all global scopes have an event loop.
2930+
2931+
<p class="example">
2932+
The {{AbortSignal/timeout(milliseconds)|timeout}} method of {{AbortSignal}}
2933+
relies on an event loop
2934+
and should not be exposed everywhere.
2935+
The rest of {{AbortSignal}} is purely computational,
2936+
and should be exposed everywhere.
2937+
</p>
2938+
2939+
The {{Exposed|[Exposed=*]}} annotation should also be applied conservatively.
2940+
If a feature is not that useful
2941+
without other features that are not exposed everywhere,
2942+
default to not exposing that feature as well.
2943+
2944+
<p class="example">
2945+
The {{Blob}} interface is purely computational,
2946+
but {{Blob}} objects are primarily used for, or obtained as a result of, I/O.
2947+
By the principle of exposing conservatively,
2948+
Blob should not be exposed everywhere.
2949+
</p>
2950+
28892951
<h3 id="new-data-formats">Add new data formats properly</h3>
28902952

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

0 commit comments

Comments
 (0)