최소 공통 웹 API

소개

웹 브라우저 외에도 다양한 ECMAScript 런타임 환경이 웹 서버 및 엣지 플랫폼에서 사용되고 있습니다. 이러한 접근 방식의 주요 이점은 여러 환경에서 단일 프로그래밍 언어를 사용할 수 있어, 전문성을 줄이고 서버와 클라이언트 측 모두에서 코드를 재사용할 수 있다는 점입니다.

웹 브라우저에서 실행되는 코드가 ECMAScript 코드의 대다수를 차지하기 때문에, 런타임은 웹 브라우저와 동일한 API를 지원하도록 유도됩니다. 그러나 구현해야 할 웹 플랫폼 API가 명확히 지정되어 있지 않으면, 이러한 환경 전반에서 상호 운용성이 떨어지는 결과를 초래합니다.

이에 따라, 본 Ecma 표준은 웹과의 상호운용성을 위해 서버 런타임이 구현해야 할 웹 플랫폼 API의 하위 집합을 정의한 최소 공통 웹 API 명세를 제정합니다. 이는 2025년 스냅샷에 해당하는 첫 번째 버전입니다. 웹 플랫폼과 웹 서버 런타임이 성장하고 발전함에 따라, 위원회는 매년 새로운 판을 발간하는 것을 목표로 할 것입니다.

이 Ecma 표준은 기술 위원회 55에서 개발되었으며, 2025년 12월 총회에서 채택되었습니다.

Copyright

ALTERNATIVE COPYRIGHT NOTICE AND COPYRIGHT LICENSE

© 2025 Ecma International

By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission under Ecma’s copyright to copy, modify, prepare derivative works of, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:

(i) The full text of this COPYRIGHT NOTICE AND COPYRIGHT LICENSE in a location viewable to users of the redistributed or derivative work.

(ii) Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the Ecma alternative copyright notice should be included.

(iii) Notice of any changes or modifications, through a copyright statement on the document such as “This document includes material copied from or derived from [title and URL of the Ecma document]. Copyright © Ecma International.”

Disclaimers

THIS WORK IS PROVIDED “AS IS,” AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

1. 적용 범위

이 표준은 W3C와 WHATWG에서 정의한 웹 플랫폼 표준의 API 중 엄선된 하위 집합인 최소 공통 웹 API의 2025년 스냅샷을 정의합니다. 이는 ECMAScript를 기반으로 한 브라우저 및 웹 서버 런타임 환경에서 공통적으로 제공되는 최소 기능 집합을 정의하기 위한 것입니다.

이 표준의 주요 대상 독자는 웹 플랫폼과의 상호운용성을 원하는 웹 서버 런타임 환경입니다. 그러나 본 표준에서 설명하는 API 집합은 주 목적이 웹 서버와 관련이 없더라도 웹과의 상호운용성을 목표로 하는 모든 ECMAScript 기반 런타임 환경에서도 구현될 수 있습니다.

2. 적합성

이 표준을 준수하는 구현체는 해당 W3C 또는 WHATWG 표준에서 정의된 대로, 본 명세에 나열된 인터페이스와 프로퍼티를 제공해야 합니다. 또한, 준수하는 구현체는 ECMA-262 표준도 따라야 합니다.

런타임별 확장은 어떤 웹 플랫폼 API이든 준수하는 런타임에서 구현할 수 있습니다. 이러한 확장은 그 사용이 어떠한 웹 플랫폼 API의 규범적 기능과 모순되거나, 비준수를 초래하지 않도록 정의되어야 합니다. 기존 API 동작을 수정하지 않더라도 API 표면을 확장하는 것은 런타임 간 코드의 상호운용성과 이식성을 저하시킬 수 있으므로 피해야 합니다.

런타임은 이 표준에 명시된 것 외의 웹 플랫폼 API를 추가로 구현할 수 있습니다.

참고: 예를 들어, Performance API는 [HR-TIME] 명세에 정의된 내용 외에 [PERFORMANCE-TIMELINE] 또는 [USER-TIMING] 명세에 정의된 것과 같은 추가 메서드나 속성으로 확장될 수 있습니다.

3. 규범적 참고문헌

다음 문서는 본문에서 일부 또는 전체 내용이 본 문서의 요구사항을 구성하는 방식으로 참조됩니다. 날짜가 명시된 참고문헌은 해당 판에만 적용됩니다. 날짜가 명시되지 않은 참고문헌은 최신 판(모든 개정 포함)이 적용됩니다.

4. 용어 및 정의

이 문서의 목적을 위해, ECMA-262, 압축 표준, 콘솔 표준, DOM 표준, 인코딩 표준, Fetch 표준, 파일 API, 고해상도 시간, HTML 표준, 스트림 표준, URL 표준, URL 패턴 표준, WebAssembly JavaScript 인터페이스, WebAssembly Web API, W3C 웹 암호화 레벨 2 및 아래에 명시된 용어와 정의를 적용한다. 외부에서 정의된 용어는 부속서 A에 출처가 표기되어 있다.

4.1. 웹 플랫폼

W3C, WHATWG 등과 같은 기구에서 정의하고 웹 브라우저에 의해 구현된 기술 표준의 조합

4.2. 웹 상호운용 런타임

이 표준을 구현하는 ECMAScript 기반 런타임 환경

참고: 웹 브라우저는 웹 상호운용 런타임입니다.
"웹 상호운용 런타임"이라는 용어는 의도적으로 넓게 정의되었습니다. 이 표준의 주요 초점은 웹 서버 런타임입니다.

5. 공통 API 색인

이 표준을 준수하는 모든 웹 상호운용 런타임은 다음의 각 웹 플랫폼 API를 구현해야 합니다. 이들은 § 6 글로벌 범위에서 지정한 경우를 제외하고, 해당 표준 요구사항에 따라 구현되어야 합니다. 기술적 또는 구조적 이유로 인해 어느 런타임 환경이 표준 요구사항에서 벗어나야 하는 경우, 명확한 문서화가 제공되어야 합니다. 문서에는 설명과 편차의 영향이 모두 포함되어야 합니다.

참고: 예를 들어, 웹 서버 런타임에는 origin 개념이 없으므로, 네트워크 요청에 [FETCH]의 요구사항인 Origin 헤더 추가를 충족할 수 없습니다.

5.1. 공통 인터페이스

다음에 나열된 모든 인터페이스는 globalThis를 통해 접근할 수 있는 글로벌 객체에 노출되어야 합니다.

[DOM]에서 정의된 인터페이스:

• AbortController

• AbortSignal

• Event

• EventTarget

[HTML]에서 정의된 인터페이스:

• CustomEvent

• ErrorEvent

• MessageChannel

• MessageEvent

• MessagePort

• PromiseRejectionEvent

[WEBIDL]에서 정의된 인터페이스:

• DOMException

[FETCH]에서 정의된 인터페이스:

• Headers

• Request

• Response

[XHR]에서 정의된 인터페이스:

• FormData

  참고: FormData 생성자는 선택적 인자로 HTMLFormElement 와 HTMLElement 타입의 인자를 받을 수 있는데, 이는 이 표준의 공통 API 목록에는 포함되지 않은 웹 API 인터페이스입니다. 두 인자 모두 생략되거나 undefined일 때의 동작은 항상 잘 정의되어 있습니다. 이러한 API를 구현하지 않는 런타임에서 다른 경우의 동작은 본 표준에서 명확하게 정의되지 않습니다. 차기 판에서 추가 명확성이 제공될 예정입니다.

[FILEAPI]에서 정의된 인터페이스:

• Blob

• File

[COMPRESSION]에서 정의된 인터페이스:

• CompressionStream

• DecompressionStream

[STREAMS]에서 정의된 인터페이스:

• ByteLengthQueuingStrategy

• CountQueuingStrategy

• ReadableByteStreamController

• ReadableStream

• ReadableStreamBYOBReader

• ReadableStreamBYOBRequest

• ReadableStreamDefaultController

• ReadableStreamDefaultReader

• TransformStream

• TransformStreamDefaultController

• WritableStream

• WritableStreamDefaultController

• WritableStreamDefaultWriter

[ENCODING]에서 정의된 인터페이스:

• TextDecoder

• TextDecoderStream

• TextEncoder

• TextEncoderStream

[URL]에서 정의된 인터페이스:

• URL

• URLSearchParams

[URLPATTERN]에서 정의된 인터페이스:

• URLPattern

[WEBCRYPTO]에서 정의된 인터페이스:

• Crypto

• CryptoKey

• SubtleCrypto

[HR-TIME]에서 정의된 인터페이스:

• Performance

[WASM-JS-API-2]에서 정의된 인터페이스:

• WebAssembly.Global

• WebAssembly.Instance

• WebAssembly.Memory

• WebAssembly.Module

• WebAssembly.Table

• WebAssembly.Tag

• WebAssembly.Exception

• WebAssembly.CompileError

• WebAssembly.LinkError

• WebAssembly.RuntimeError

5.2. 공통 메서드와 속성

다음에 나열된 모든 메서드와 속성은 globalThis를 통해 접근할 수 있는 글로벌 객체에 노출되어야 하며, § 6 글로벌 범위에서 지정한 경우는 예외입니다.

• globalThis ([ECMASCRIPT]에 정의됨)

[HTML]에서 정의된 메서드와 속성:

• globalThis.atob()

• globalThis.btoa()

• globalThis.clearTimeout()

• globalThis.clearInterval()

• globalThis.navigator.userAgent

• globalThis.onerror

• globalThis.onunhandledrejection

• globalThis.onrejectionhandled

• globalThis.queueMicrotask()

• globalThis.reportError()

• globalThis.self

• globalThis.setTimeout()

• globalThis.setInterval()

• globalThis.structuredClone()

[FETCH]에서 정의된 메서드와 속성:

• globalThis.fetch()

[CONSOLE]에서 정의된 메서드와 속성:

• globalThis.console

[WEBCRYPTO]에서 정의된 메서드와 속성:

• globalThis.crypto

[HR-TIME]에서 정의된 메서드와 속성:

• globalThis.performance

[WASM-JS-API-2]에서 정의된 메서드와 속성:

• globalThis.WebAssembly.compile()

• globalThis.WebAssembly.compileStreaming()

• globalThis.WebAssembly.instantiate()

• globalThis.WebAssembly.instantiateStreaming()

• globalThis.WebAssembly.JSTag

• globalThis.WebAssembly.validate()

5.3. 웹 워커

이 표준은 웹 워커 지원을 런타임에 요구하지 않습니다. 하지만, 런타임에 WorkerGlobalScope에 매핑되는 글로벌 스코프가 있는 경우(§ 6 글로벌 범위 참조), 아래 이벤트 핸들러 및 속성은 [HTML]에 정의된 대로 글로벌 객체에 노출되어야 하며, § 6 글로벌 범위에서 지정된 경우는 예외입니다.

• onerror

• onunhandledrejection

• onrejectionhandled

• self

6. 글로벌 범위

글로벌 범위(globalThis)의 정확한 타입은 런타임마다 다를 수 있습니다. 대부분의 웹 플랫폼 API는 Window, WorkerGlobalScope 등과 같은 타입이 노출된 웹 브라우저 환경을 전제로 정의되어 있습니다. 준수를 단순화하기 위해, 본 표준은 이러한 글로벌 스코프 인터페이스를 지원할 것을 요구하지 않지만, 각 런타임의 글로벌 스코프는 웹 명세에서 정의된 글로벌 스코프 인터페이스에 매핑될 수 있습니다. 본 표준에 의해 정의된 모든 인터페이스, 메서드, 속성은 웹 명세에서 글로벌 스코프 인터페이스에 노출되어야 하는 경우, 런타임의 해당 글로벌 스코프(예: globalThis.crypto, globalThis.ReadableStream 등)에서 노출되어야 합니다.

참고: 런타임의 메인 글로벌 스코프는 Window, 웹 워커 글로벌 스코프는 WorkerGlobalScope 등에 매핑되어야 합니다. 특히 정의된 글로벌 인터페이스에 매핑되지 않는 글로벌 스코프는 [Exposed=*]로 정의된 웹 API만 구현할 수 있습니다.

많은 런타임에서 새로운 글로벌 스코프 속성을 추가하면 기존 애플리케이션 코드와 충돌 시 호환성에 문제가 생길 수 있습니다. 많은 웹 플랫폼 API는 the readonly 속성을 사용해 글로벌 속성을 정의합니다. 호환성 문제를 방지하기 위해, 본 표준을 준수하는 런타임은 글로벌 스코프에 속성을 추가할 때 readonly 속성 생략을 허용합니다. 이를 통해 런타임 사용자들은 기존 코드와 충돌하는 속성을 삭제하거나 덮어쓸 수 있게 됩니다.

글로벌 객체가 Window 또는 WorkerGlobalScope 글로벌 인터페이스에 해당하는 경우, 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` 값은 애플리케이션 코드가 실행 중인 런타임을 신뢰성 있게 식별할 수 있도록 제공됩니다. 값은 User-Agent 구성에 부합하는 문자열이어야 하며, [RFC7231]에 정의되어 있습니다:

User-Agent      = product *( RWS ( product / comment ) )
product         = token ["/" product-version]
product-version = token

기본 `User-Agent` 값은 애플리케이션 코드에서 단일, 완전하며, 불투명하고, 비구조적인 값으로 취급해야 합니다. 값에는 선택적인 product-version을 제외한 하나의 product 토큰만 포함하는 것이 권장됩니다. 값에는 comment 구성요소가 포함되지 않아야 합니다.

참고: 예를 들어, navigator.userAgent 값은 'MyRuntime'으로 설정할 수 있습니다.