소개
웹 브라우저를 넘어 웹 서버 및 엣지 플랫폼에서 사용되는 다양한 JavaScript 런타임 환경이 널리 활용되고 있습니다. JavaScript가 서버와 클라이언트 양쪽에서 모두 사용할 수 있다는 점이 중요한 이유 중 하나인데, 이는 단일 코드베이스의 여러 부분을 작업할 때 필요한 전문화가 줄어들고, 서버와 클라이언트 간에 코드를 재사용할 수 있게 해줍니다.
하지만 웹 브라우저에서 실행되는 코드가 JavaScript 코드의 대부분을 차지하기 때문에, 이러한 런타임이 웹 브라우저와 동일한 API를 지원하면 도움이 됩니다. 그래서 점점 더 많은 런타임 환경이 웹 플랫폼 API를 지원하기 시작했습니다. 그러나 이러한 환경의 증가와 웹 플랫폼 API 선택의 다양성으로 인해 환경 간 상호운용성이 떨어지는 문제가 생겼습니다.
이에 따라 이 Ecma 표준은 서버 및 엣지 런타임이 웹 상호운용을 목표로 할 경우 구현해야 하는 웹 플랫폼 API의 엄선된 최소 하위 집합인 최소 공통 웹 API 명세를 정의합니다. 이는 2025 스냅샷에 해당하는 표준의 첫 번째 버전이며, 매년 추가 스냅샷이 발행될 예정입니다.
1. 적용 범위
이 표준은 브라우저 및 비브라우저 JavaScript 기반 런타임 환경에 공통적인 최소 기능을 정의하기 위해 W3C와 WHATWG에서 정의된 웹 플랫폼 표준의 API 중 엄선된 하위 집합인 최소 공통 웹 플랫폼 API의 2025 스냅샷을 정의합니다.
2. 적합성
최소 공통 웹 플랫폼 API의 적합한 구현은 ECMA-262를 준수해야 하며, 추가로 이 명세에 나열된 인터페이스와 속성을 해당 W3C 또는 WHATWG 표준에 따라 제공해야 합니다.
적합한 런타임은 특정 Web 플랫폼 API에 런타임별 확장을 구현할 수 있습니다. 이러한 확장은 Web 플랫폼 API의 규범적 기능과 모순되거나 비적합성을 초래하지 않도록 정의되어야 합니다. 이러한 확장 기능의 사용은 런타임 간 코드의 상호운용성과 이식성을 떨어뜨리므로 신중히 고려해야 합니다.
이 명세는 여기에 나열된 것 외의 추가 Web 플랫폼 API 구현을 금지하지 않습니다.
참고: 예를 들어, Performance
API는 [HR-TIME]
명세에 정의된 것 외에도 [PERFORMANCE-TIMELINE] 또는 [USER-TIMING] 명세에 정의된 메서드나 속성으로 확장될 수 있습니다.
3. 규범적 참고문헌
다음 문서는 본문에서 일부 또는 전체 내용이 본 문서의 요구사항을 구성하는 방식으로 참조됩니다. 날짜가 명시된 참고문헌은 해당 판에만 적용됩니다. 날짜가 명시되지 않은 참고문헌은 최신 판(모든 개정 포함)이 적용됩니다.
참고문헌
규범적 참고문헌
- [COMPRESSION]
- Adam Rice. Compression Standard. Living Standard. URL: https://compression.spec.whatwg.org/
- [CONSOLE]
- Dominic Farolino; Robert Kowalski; Terin Stock. Console Standard. Living Standard. URL: https://console.spec.whatwg.org/
- [DOM]
- Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
- [ECMASCRIPT]
- ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
- [ENCODING]
- Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
- [FETCH]
- Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
- [FILEAPI]
- Marijn Kruisselbrink. File API. URL: https://w3c.github.io/FileAPI/
- [HR-TIME]
- Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
- [HTML]
- Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
- [RFC7231]
- R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html
- [STREAMS]
- Adam Rice; et al. Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
- [URL]
- Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
- [URLPATTERN]
- Ben Kelly; Jeremy Roman; 宍戸俊哉 (Shunya Shishido). URL Pattern Standard. Living Standard. URL: https://urlpattern.spec.whatwg.org/
- [WASM-JS-API-2]
- . Ms2ger. WebAssembly JavaScript Interface. URL: https://webassembly.github.io/spec/js-api/
- [WASM-WEB-API-2]
- . Ms2ger. WebAssembly Web API. URL: https://webassembly.github.io/spec/web-api/
- [WEBCRYPTO]
- Daniel Huigens. Web Cryptography Level 2. URL: https://w3c.github.io/webcrypto/
- [WEBIDL]
- Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
- [XHR]
- Anne van Kesteren. XMLHttpRequest Standard. Living Standard. URL: https://xhr.spec.whatwg.org/
참고용 참고문헌
- [PERFORMANCE-TIMELINE]
- Nicolas Pena Moreno. Performance Timeline. URL: https://w3c.github.io/performance-timeline/
- [USER-TIMING]
- Nicolas Pena Moreno. User Timing Level 3. URL: https://w3c.github.io/user-timing/
4. 용어 및 정의
4.1. 웹 플랫폼
웹 플랫폼은 W3C, WHATWG 등과 같은 조직에서 정의한 기술 표준의 조합으로, 웹 브라우저에서 구현됩니다.
4.2. 웹 상호운용 런타임
이 명세에서 설명된 웹 플랫폼 API의 하위 집합을 구현하는 ECMAScript 기반 애플리케이션 런타임 환경입니다.
이 용어는 웹 브라우저도 포함할 수 있도록 넓게 정의되었지만, 여기서는 비브라우저 런타임에 대한 기대를 설명하는 데 중점을 둡니다.
5. 공통 API 색인
이 명세를 준수하는 모든 웹 상호운용 런타임은 다음 웹 플랫폼 API를 모두 구현해야 합니다. 여기서 수정된 부분을 제외하고는 규범적 요구사항에 따라 구현되어야 합니다. 어떤 런타임 환경이 명세의 규범적 요구사항에서 벗어나는 경우, 그 이유와 내용을 문서에서 명확하고 쉽게 찾을 수 있도록 제공해야 합니다.
다음 모든 인터페이스는 명세에서 별도로 지정하지 않는 한 globalThis
를 통해 접근 가능한 글로벌 객체에 노출되어야 합니다:
다음 모든 메서드와 속성도 명세에서 별도로 지정하지 않는 한 globalThis
를 통해 접근 가능한 글로벌 객체에 노출되어야 합니다:
-
globalThis.
clearTimeout()
[HTML] -
globalThis.
clearInterval()
[HTML] -
globalThis.
crypto
[WEBCRYPTO] -
globalThis.
onunhandledrejection
[HTML] -
globalThis.
onrejectionhandled
[HTML] -
globalThis.
performance
[HR-TIME] -
globalThis.
queueMicrotask()
[HTML] -
globalThis.
reportError()
[HTML] -
globalThis.
setTimeout()
[HTML] -
globalThis.
setInterval()
[HTML] -
globalThis.
structuredClone()
[HTML] -
globalThis.
WebAssembly
.compile()
[WASM-JS-API-2] -
globalThis.
WebAssembly
.compileStreaming()
[WASM-WEB-API-2] -
globalThis.
WebAssembly
.instantiate()
[WASM-JS-API-2] -
globalThis.
WebAssembly
.instantiateStreaming()
[WASM-WEB-API-2] -
globalThis.
WebAssembly
.JSTag
[WASM-JS-API-2] -
globalThis.
WebAssembly
.validate()
[WASM-JS-API-2]
workers를 지원하는 웹 상호운용 런타임은 onerror
,
onunhandledrejection
,
onrejectionhandled
그리고
self
를 worker의 globalThis
에 노출해야 합니다.
명세에서 별도로 지정하지 않는 한. [HTML]
6. 글로벌 스코프
글로벌 스코프(globalThis
)의 정확한 타입은 런타임마다 다를 수 있습니다. 대부분의 웹 플랫폼 API는 Window
,
WorkerGlobalScope
와 같은 타입을 노출하는 웹 브라우저 환경을 전제로 정의되어 있습니다. 적합성을 쉽게 하기 위해, 이 명세에서 정의된 모든 인터페이스, 메서드, 속성은 런타임의 적절한 글로벌 스코프(예:
globalThis.crypto
, globalThis.ReadableStream
등)에 노출되어야 합니다.
많은 런타임에서는 새로운 글로벌 범위 속성을 추가할 때, 해당 글로벌이 기존 애플리케이션 코드와 충돌하면 호환성 문제가 발생할 수 있습니다. 다수의 웹 플랫폼 API는 readonly
특성을 사용하여 글로벌 속성을 정의합니다. [WEBIDL] 이러한 호환성 문제를 방지하기 위해, 이 명세를 준수하는 런타임은 글로벌 범위에
추가되는 속성에 대해 readonly
특성을 무시할 수 있습니다. 이를 통해 해당 런타임의 사용자는 기존 애플리케이션 코드와 충돌 시 이러한 속성을 삭제하거나 덮어쓸 수
있습니다.
Window
와
유사한 환경 및 워커 환경의 글로벌 객체는 항상 EventTarget
의
인스턴스여야 합니다. 웹 상호운용 런타임은 예외 보고 알고리즘과 자바스크립트 HostPromiseRejectionTracker 호스트
훅을 따라야 하며, 이는 [HTML]에 정의되어 있습니다.
여기에는 글로벌 객체에서 error
,
unhandledrejection
및 rejectionhandled
이벤트를 발생시키는 것이 포함됩니다.
레거시 사유로 글로벌 객체가 EventTarget
의
인스턴스가 될 수 없는 경우에도, 관련 이벤트는 글로벌 스코프에서 사용 가능한 적절한 대체 메커니즘을 통해 여전히 발생해야 합니다. 이 메커니즘은 만약 글로벌 객체가 EventTarget
였다면
제공되는 정보와 동일한 정보를 최소한 제공해야 합니다. 이러한 런타임은 onerror
,
onunhandledrejection
및 onrejectionhandled
글로벌 속성을 지원하지 않아야 합니다. 또한 ErrorEvent
및 PromiseRejectionEvent
인터페이스를 구현할 필요가 없습니다.
참고: 예를 들어 Node.js에서는 글로벌 객체가 EventTarget
을
구현하지 않으며, 관련 이벤트는 globalThis.process
객체에서 uncaughtException
,
unhandledRejection
, rejectionHandled
등의 이름으로 발생합니다.
7. 기본 User-Agent 값 요구사항
기본 `User-Agent` 값은 애플리케이션 코드가 실행 중인 런타임을 신뢰성 있게 식별할 수 있도록
제공됩니다. 값은
구성에 부합하는 문자열이어야 하며, [RFC7231]에
정의되어 있습니다:User-Agent
User-Agent = product *( RWS ( product / comment ) ) product = token ["/" product-version] product-version = token
기본 `User-Agent` 값은 하나의 완전하고 불투명하며 구조화되지 않은 값으로 처리되어야 합니다. 값은
선택적 product-version
을 제외한 단일 product
토큰으로 제한하는 것이 권장됩니다. 값에 comment
구성
요소는 포함하지 않아야 합니다.
참고: 예를 들어, navigator.userAgent
값은 'MyRuntime'
으로 설정할 수 있습니다.
색인
이 명세서에서 정의한 용어
- 웹 상호운용 런타임, in § 4.2
- 웹 플랫폼, in § 4.1
참고문헌에서 정의한 용어
-
[COMPRESSION]에서 정의된 용어:
- CompressionStream
- DecompressionStream
-
[CONSOLE]에서 정의된 용어:
- console
-
[DOM]에서 정의된 용어:
- AbortController
- AbortSignal
- CustomEvent
- Event
- EventTarget
-
[ECMASCRIPT]에서 정의된 용어:
- globalThis
-
[ENCODING]에서 정의된 용어:
- TextDecoder
- TextDecoderStream
- TextEncoder
- TextEncoderStream
-
[FETCH]에서 정의된 용어:
- Headers
- Request
- Response
- default `User-Agent` value
- fetch(input)
-
[FILEAPI]에서 정의된 용어:
- Blob
- File
-
[HR-TIME]에서 정의된 용어:
- Performance
- performance
-
[HTML]에서 정의된 용어:
- ErrorEvent
- MessageChannel
- MessageEvent
- MessagePort
- PromiseRejectionEvent
- Window
- WorkerGlobalScope
- atob(data)
- btoa(data)
- clearInterval(id)
- clearTimeout(id)
- error
- navigator
- onerror (GlobalEventHandlers용)
- onerror (WorkerGlobalScope용)
- onrejectionhandled (WindowEventHandlers용)
- onrejectionhandled (WorkerGlobalScope용)
- onunhandledrejection (WindowEventHandlers용)
- onunhandledrejection (WorkerGlobalScope용)
- queueMicrotask(callback)
- rejectionhandled
- report an exception
- reportError(e)
- self (Window용)
- self (WorkerGlobalScope용)
- setInterval(handler, timeout, ...arguments)
- setTimeout(handler, timeout, ...arguments)
- structuredClone(value, options)
- unhandledrejection
- userAgent
-
[STREAMS]에서 정의된 용어:
- ByteLengthQueuingStrategy
- CountQueuingStrategy
- ReadableByteStreamController
- ReadableStream
- ReadableStreamBYOBReader
- ReadableStreamBYOBRequest
- ReadableStreamDefaultController
- ReadableStreamDefaultReader
- TransformStream
- TransformStreamDefaultController
- WritableStream
- WritableStreamDefaultController
- WritableStreamDefaultWriter
-
[URL]에서 정의된 용어:
- URL
- URLSearchParams
-
[URLPATTERN]에서 정의된 용어:
- URLPattern
-
[WASM-JS-API-2]에서 정의된 용어:
- CompileError
- Exception
- Global
- Instance
- JSTag
- LinkError
- Memory
- Module
- RuntimeError
- Table
- Tag
- WebAssembly
- compile(bytes)
- instantiate(bytes)
- validate(bytes)
-
[WASM-WEB-API-2]에서 정의된 용어:
- compileStreaming(source)
- instantiateStreaming(source)
-
[WEBCRYPTO]에서 정의된 용어:
- Crypto
- CryptoKey
- SubtleCrypto
- crypto
-
[WEBIDL]에서 정의된 용어:
- DOMException
- read only
-
[XHR]에서 정의된 용어:
- FormData
Copyright & Software License
Ecma International
Rue du Rhone 114
CH-1204 Geneva
Tel: +41 22 849 6000
Fax: +41 22 849 6001
Web: https://ecma-international.org/
Copyright Notice
© 2025 Ecma International
This draft document may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as needed for the purpose of developing any document or deliverable produced by Ecma International.
This disclaimer is valid only prior to final version of this document. After approval all rights on the standard are reserved by Ecma International.
The limited permissions are granted through the standardization phase and will not be revoked by Ecma International or its successors or assigns during this time.
This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Software License
All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.