-
Notifications
You must be signed in to change notification settings - Fork 13
/
index.bs
136 lines (111 loc) · 7.13 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
<pre class='metadata'>
Title: Minimum Common Web Platform API
Shortname: minimum-common-api
Group: wintercg
Status: w3c/CG-DRAFT
Level: none
URL: https://min-common-api.proposal.wintercg.org/
Repository: https://github.com/wintercg/proposal-minimum-common-api
Editor: James M Snell, Cloudflare https://cloudflare.com/, jsnell@cloudflare.com
Abstract: Minimum Common Web Platform API for Non-Browser ECMAScript-based runtimes.
Markup Shorthands: markdown yes
</pre>
<pre class=link-defaults>
spec:url; type:interface; text:URL
spec:html; type:attribute; for:Window; text:navigator
spec:fetch; type:method; text:fetch()
</pre>
Introduction {#intro}
=====================
*This section is non-normative.*
The Minimum Common Web Platform API is a curated subset of standardized Web Platform APIs intended to define a minimum set of capabilities common to Browser and Non-Browser JavaScript-based runtime environments.
Terminology {#terminology}
==========================
The Web Platform is the combination of technology standards defined by organizations such as the W3C, the WHATWG, and others as implemented by Web Browsers.
A <dfn>Web-interoperable Runtime</dfn> is any ECMAScript-based application runtime environment that implements the subset of Web Platform APIs outlined in this specification.
While this term is intentionally broad to also encompass Web Browsers, the primary focus here is on outlining expectations for non-browser runtimes.
Common API Index {#api-index}
=========================
All <a>Web-interoperable Runtimes</a> conforming to this specification SHALL implement each of the following Web Platform APIs in accordance with their normative requirements except where modified here. Where any conforming runtime environment chooses (either by necessity or otherwise) to diverge from a normative requirement of the specification, clear explanations of such divergence MUST be made clearly and readily available in the documentation.
Interfaces:
* {{AbortController}}
* {{AbortSignal}}
* {{Blob}}
* {{ByteLengthQueuingStrategy}}
* <code class="idl"><a data-link-type="idl" href="https://wicg.github.io/compression/#compression-stream">CompressionStream</a></code>
* {{CountQueuingStrategy}}
* {{Crypto}}
* {{CryptoKey}}
* <code class="idl"><a data-link-type="idl" href="https://wicg.github.io/compression/#decompression-stream">DecompressionStream</a></code>
* {{DOMException}}
* {{Event}}
* {{EventTarget}}
* {{File}}
* {{FormData}}
Issue: The {{FormData}} constructor optionally takes {{HTMLFormElement}} and {{HTMLElement}} as parameters.
TODO: Figure out what implementations without DOM support should do here.
Node.js and Deno throw if the first parameter is not `undefined` but ignore the second parameter.
Cloudflare Workers ignores all parameters.
* {{Headers}}
* {{ReadableByteStreamController}}
* {{ReadableStream}}
* {{ReadableStreamBYOBReader}}
* {{ReadableStreamBYOBRequest}}
* {{ReadableStreamDefaultController}}
* {{ReadableStreamDefaultReader}}
* {{Request}}
* {{Response}}
* {{SubtleCrypto}}
* {{TextDecoder}}
* {{TextDecoderStream}}
* {{TextEncoder}}
* {{TextEncoderStream}}
* {{TransformStream}}
* {{TransformStreamDefaultController}}
* {{URL}}
* {{URLSearchParams}}
* {{WebAssembly}}.<l spec="wasm-js-api">{{Global}}</l>
* {{WebAssembly}}.<l spec="wasm-js-api">{{Instance}}</l>
* {{WebAssembly}}.<l spec="wasm-js-api">{{Memory}}</l>
* {{WebAssembly}}.<l spec="wasm-js-api">{{Module}}</l>
* {{WebAssembly}}.<l spec="wasm-js-api">{{Table}}</l>
* {{WritableStream}}
* {{WritableStreamDefaultController}}
Global methods / properties:
* <code class="idl"><a data-link-type="idl" href="https://tc39.es/ecma262/multipage/global-object.html#sec-globalthis">globalThis</a></code>
* globalThis.{{atob()}}
* globalThis.{{btoa()}}
* globalThis.{{console}}
* globalThis.{{crypto}}
* globalThis.{{fetch()}}
* globalThis.{{navigator}}.{{userAgent}}
* globalThis.{{performance}}.{{Performance/now()}}
* globalThis.{{performance}}.{{timeOrigin}}
* globalThis.{{queueMicrotask()}}
* globalThis.{{setTimeout()}} / globalThis.{{clearTimeout()}}
* globalThis.{{setInterval()}} / globalThis.{{clearInterval()}}
* globalThis.{{structuredClone()}}
* globalThis.{{WebAssembly}}.{{WebAssembly/compile()}}
* globalThis.{{WebAssembly}}.{{WebAssembly/compileStreaming()}}
* globalThis.{{WebAssembly}}.{{WebAssembly/instantiate()}}
* globalThis.{{WebAssembly}}.{{WebAssembly/instantiateStreaming()}}
* globalThis.{{WebAssembly}}.{{WebAssembly/validate()}}
Note: This list includes APIs defined in [[FETCH]]. The WinterCG is currently working on a fork of this spec to better fulfill the needs of web-interoperable runtimes, and such runtimes should follow this fork instead. See <a href="https://fetch.spec.wintercg.org">https://fetch.spec.wintercg.org</a>.
The Global Scope {#global-scope}
================================
The exact type of the global scope (`globalThis`) can vary across runtimes. Most Web Platform APIs are defined in terms that assume Web Browser environments that specifically expose types like {{Window}}, {{Worker}}, {{WorkerGlobalScope}}, and so forth. To simplify conformance, all Interfaces, methods, and properties defined by this specification MUST be exposed on the runtime's relevant global scope (e,g., `globalThis.crypto`, `globalThis.ReadableStream`, etc).
With many runtimes, adding a new global-scoped property can introduce breaking changes when the new global conflicts with existing application code. Many Web Platform APIs define global properties using the `readonly` attribute. To avoid introducing breaking changes, runtimes conforming to this specification MAY choose to ignore the `readonly` attribute for properties being added to the global scope.
Requirements for navigator.userAgent {#navigator-useragent-requirements}
========================================================================
The globalThis.{{navigator}}.{{userAgent}} property is provided such that application code can reliably identify the runtime within which it is running.
The value of the property is a string conforming to the <code class="idl"><a data-link-type="idl" href="https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3">`User-Agent`</a></code> construction in RFC 7231:
<pre>
User-Agent = product *( RWS ( product / comment ) )
product = token ["/" product-version]
product-version = token
</pre>
While runtimes that implement globalThis.{{navigator}}.{{userAgent}} MUST provide a value that is conformant with the structure defined by RFC 7231, the value SHOULD be treated as a single, complete, opaque, unstructured value. It is RECOMMENDED that the value be limited to a single `product` token excluding the optional `product-version`. For instance, `navigator.userAgent = 'MyRuntime'`. The value SHOULD NOT include any `comment` components.
Extensions {#extensions}
========================
Runtime-specific extensions to any Web Platform API MAY be implemented by conforming runtimes. Such extensions MUST be defined so that their use neither contradicts nor causes the non-conformance of normative functionality of any Web Platform API.
Application use of such extensions must be carefully considered, as doing so reduces interoperability and portability of code across runtimes.