Skip to content

Commit e7d70ad

Browse files
committed
New text for guidance on exposing interfaces everywhere
Closes: #509
1 parent 55a06e0 commit e7d70ad

1 file changed

Lines changed: 64 additions & 0 deletions

File tree

index.bs

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2756,6 +2756,70 @@ because use of {{ScriptProcessorNode}} from the main thread
27562756
frequently resulted in a poor user experience. [[WebAudio]]
27572757
</p>
27582758

2759+
## Only purely computational features should be exposed everywhere ## {#expose-everywhere}
2760+
<!--
2761+
https://github.com/w3ctag/design-principles/issues/509
2762+
https://github.com/whatwg/webidl/issues/468
2763+
https://github.com/w3ctag/design-principles/issues/35
2764+
-->
2765+
2766+
When exposing a feature,
2767+
please consider whether it makes sense
2768+
to expose the feature to all possible environments
2769+
(via the {{Exposed|[Exposed=*]}} annotation
2770+
or including it on all global scope interfaces).
2771+
2772+
Only purely computational features should be exposed everywhere.
2773+
That is,
2774+
they do not perform I/O
2775+
and do not affect the state of the user agent or the user’s device.
2776+
2777+
<p class="example">
2778+
The {{TextEncoder}} interface converts a string to UTF-8 encoded bytes.
2779+
This is a purely computational interface,
2780+
generally useful as a JavaScript language facility,
2781+
so it should be exposed everywhere.
2782+
</p>
2783+
2784+
<p class="example">
2785+
<a attribute spec=html>localStorage</a> affects the state of the user agent, so it should not be exposed everywhere.
2786+
</p>
2787+
2788+
<p class="example">
2789+
Technically, {{console}} could affect the state of the user agent
2790+
(by causing log messages to appear in the developer tools)
2791+
or the user’s device
2792+
(by writing to a log file.)
2793+
But these things are not observable from the running code,
2794+
and the practicality of having {{console}} everywhere outweighs the disadvantages.
2795+
</p>
2796+
2797+
Additionally, anything annotated with {{SecureContext}},
2798+
or relying on an event loop,
2799+
should not be exposed everywhere.
2800+
Not all global scopes are secure contexts
2801+
or have an event loop.
2802+
2803+
<p class="example">
2804+
The {{AbortSignal/timeout(milliseconds)|timeout}} method of {{AbortSignal}}
2805+
relies on an event loop
2806+
and should not be exposed everywhere.
2807+
The rest of {{AbortSignal}} is purely computational,
2808+
and should be exposed everywhere.
2809+
</p>
2810+
2811+
The {{Exposed|[Exposed=*]}} annotation should also be applied conservatively.
2812+
If a feature is not that useful
2813+
without other features that are not exposed everywhere,
2814+
default to not exposing that feature as well.
2815+
2816+
<p class="example">
2817+
The {{Blob}} interface is purely computational,
2818+
but {{Blob}} objects are primarily used for, or obtained as a result of, I/O.
2819+
By the principle of exposing conservatively,
2820+
Blob should not be exposed everywhere.
2821+
</p>
2822+
27592823
<h3 id="new-data-formats">Add new data formats properly</h3>
27602824

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

0 commit comments

Comments
 (0)