Module sync assert S1

Proposal details

Stage: Stage 1
Status: Active
ECMAScript edition: —
Synchronized: Aug 28, 2026
中文译文 · Source repository

Proposal overview

This proposal addresses the problem of modules accidentally becoming asynchronous, which can break synchronous-dependent code in scenarios like Service Workers, polyfills, and API stability. The solution introduces a new directive, "assert sync", which instructs the engine to fail early with a syntax error if the module or its subgraph is async. The proposal is at an early stage, having only a README without formal specification or implementation details.

Note

The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

Module sync assert

Problem to solve

Some code must be synchronous. If the module accidentally becomes async (by having a top-level await or the old semantics of WebAssembly ESM integration in the subgraph) the code might break in a way that hard to debug.

Example: Service Worker

import './some-module.js'
addEventListener('fetch', () => {})

NOTE

If you try to use the native implementation of the ES Module in Service Worker, it will throw a TypeError "Top-level await is disallowed in service workers.".

Let's assume the service worker is bundled via a bundler and transformed into a non-ES module format.

If some-module.js becomes async, then the addEventListener no longer works:

WARNING

Event handler of 'fetch' event must be added on the initial evaluation of worker script.

Example: Polyfill

The polyfill code must run synchronously, otherwise, the application might be broken in old browsers.

Example: API stability

Adding TLA is a breaking change, the library author may want to add a test that their library won't accentually become async due to dependency changes.

Solution

Adding a hint to the engine, if the module evaluation is async or contains an async subgraph, the engine should fail early (syntax error), so the developer can fix it early.

Directive

"assert sync"

Adding a new directive to hint the engine.

#Module sync assert S1

#Module sync assert

#Problem to solve

#Example: Service Worker

#Example: Polyfill

#Example: API stability

#Solution

#Directive

#Other solutions: Linter/bundler level bans