rollup-plugin-concurrent-top-level-await 0.0.1

package/README.md

@@ -0,0 +1,81 @@
+# rollup-plugin-concurrent-top-level-await
+
+Rollup (and therefore also Vite) will change the behavior of modules containing top level await (TLA):
+they run sequentially instead of concurrently, as described in
+[the Rolldown docs](https://github.com/rolldown/rolldown/blob/main/docs/in-depth/tla-in-rolldown.md).
+This Vite-compatible plugin enables concurrent execution of TLA modules.
+
+Note that this plugin requires TLA support at runtime; it does _not_ provide a TLA polyfill.
+For that, check out [vite-plugin-top-level-await](https://www.npmjs.com/package/vite-plugin-top-level-await).
+
+## Installation
+
+Using npm:
+
+```bash
+npm install rollup-plugin-concurrent-top-level-await --save-dev
+```
+
+## Usage
+
+```ts
+import concurrentTopLevelAwait from "rollup-plugin-concurrent-top-level-await";
+
+export default {
+	plugins: [
+		concurrentTopLevelAwait({
+			include: "**/*.ts",
+		}),
+	],
+};
+```
+
+## Known Limitations
+
+### Execution Order
+
+We currently prioritize minimizing the required code transformations over complete compliance with the standard.
+As a result, the execution order of TLA modules may differ from the standard behavior in certain cases, as can be seen
+by the results for [tla-fuzzer](https://github.com/evanw/tla-fuzzer):
+
+| Variant                  | Rollup | Rollup with Plugin |
+| ------------------------ | ------ | ------------------ |
+| Simple                   | 80%    | 100%               |
+| Trailing Promise         | 10%    | 94%                |
+| Cyclic                   | 69%    | 77%                |
+| Cyclic, Trailing Promise | 15%    | 64%                |
+
+Please do not rely on a specific execution order when using this plugin.
+
+We might adapt Webpack's approach in the future to improve correctness.
+
+### Build Performance
+
+To transform a module, the plugin needs to check if any of its dependencies is async. Hence, the transformation is
+postponed until the subgraph is analyzed. This may lead to slower builds.
+
+If you notice significant performance degradation, please open an issue.
+
+### Changing Variable Types
+
+In the process of transforming the code, top level `const` declarations may get replaced with `let` declarations. This
+can lead to `const` variables being assignable at runtime instead of throwing an invalid assignment error.
+
+Additionally, variable declarations may be hoisted, which removes temporal dead zone (TDZ) checks.
+
+### Exporting var
+
+The plugin only checks the very top level of a module for potentially exported variables. This means that if a `var`
+variable is declared inside a block but exported, the variable might not get handled correctly.
+
+```js
+if (something) {
+	var myValue = 42;
+}
+export default myValue;
+```
+
+### Class Decorators
+
+Class declarations still get evaluated before any top level await expressions. This means that if a class decorator
+relies on a top level await expression, it may not work as expected.

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import { FilterPattern } from "@rollup/pluginutils";
+import * as rollup0 from "rollup";
+
+//#region src/index.d.ts
+declare function concurrentTopLevelAwait(options?: {
+  include?: FilterPattern;
+  exclude?: FilterPattern;
+}): {
+  name: string;
+  apply: string;
+  transform: {
+    handler(this: rollup0.TransformPluginContext, code: string, id: string): Promise<{
+      code: string;
+      meta: {
+        async: true;
+      };
+    } | undefined>;
+  };
+  resolveImportMeta(this: rollup0.PluginContext, property: string | null, {
+    moduleId,
+    chunkId
+  }: {
+    chunkId: string;
+    format: rollup0.InternalModuleFormat;
+    moduleId: string;
+  }): "true" | "false" | undefined;
+};
+//#endregion
+export { concurrentTopLevelAwait as default };

package/dist/index.mjs

@@ -0,0 +1,242 @@
+import { createFilter } from "@rollup/pluginutils";
+import MagicString from "magic-string";
+
+//#region src/hasTopLevelAwait.ts
+function hasTopLevelAwait(ast) {
+	let found = false;
+	function isFunctionNode(node) {
+		if (!node || typeof node.type !== "string") return false;
+		return node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression" || node.type === "ClassPrivateMethod" || node.type === "MethodDefinition";
+	}
+	function walk(node, functionDepth = 0) {
+		if (!node || found) return;
+		if (node.type === "AwaitExpression" && functionDepth === 0) {
+			found = true;
+			return;
+		}
+		const nextDepth = functionDepth + (isFunctionNode(node) ? 1 : 0);
+		for (const key of Object.keys(node)) {
+			const child = node[key];
+			if (Array.isArray(child)) for (const c of child) walk(c, nextDepth);
+			else if (child && typeof child.type === "string") walk(child, nextDepth);
+		}
+	}
+	walk(ast, 0);
+	return found;
+}
+
+//#endregion
+//#region src/polyfills/promise.ts
+function withResolvers() {
+	let resolve;
+	let reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+
+//#endregion
+//#region src/AsyncTlaTracker.ts
+var AwaitableCache = class {
+	#store = /* @__PURE__ */ new Map();
+	#getPromise(key) {
+		const entry = this.#store.get(key);
+		if (entry) return entry;
+		const { promise, resolve } = withResolvers();
+		this.#store.set(key, [promise, resolve]);
+		return [promise, resolve];
+	}
+	set(key, value) {
+		const [_, resolve] = this.#getPromise(key);
+		resolve(value);
+	}
+	get(key) {
+		const [promise] = this.#getPromise(key);
+		return promise;
+	}
+};
+var AsyncTlaTracker = class {
+	#all = /* @__PURE__ */ new Set();
+	#unseen = /* @__PURE__ */ new Set();
+	#unresolved = /* @__PURE__ */ new Set();
+	#resultCache = new AwaitableCache();
+	get(key) {
+		return this.#resultCache.get(key);
+	}
+	setMarked(key, value) {
+		this.#all.add(key);
+		this.#unseen.delete(key);
+		this.#unresolved.delete(key);
+		this.#resultCache.set(key, true);
+		setTimeout(() => {
+			if (this.#unseen.size == 0) {
+				this.#unresolved.forEach((e) => this.#resultCache.set(e, false));
+				this.#all.forEach((e) => this.#resultCache.set(e, false));
+				this.#unresolved.clear();
+			}
+		}, 0);
+	}
+	setChildren(key, children) {
+		if (!this.#all.has(key)) {
+			this.#all.add(key);
+			this.#unresolved.add(key);
+		}
+		this.#unseen.delete(key);
+		children.forEach((children$1) => {
+			if (!this.#all.has(children$1)) {
+				this.#all.add(children$1);
+				this.#unresolved.add(key);
+				this.#unseen.add(children$1);
+			}
+			this.#resultCache.get(children$1).then((value) => {
+				if (value) this.setMarked(key, true);
+			});
+		});
+		setTimeout(() => {
+			if (this.#unseen.size == 0) {
+				this.#unresolved.forEach((e) => this.#resultCache.set(e, false));
+				this.#all.forEach((e) => this.#resultCache.set(e, false));
+				this.#unresolved.clear();
+			}
+		}, 0);
+	}
+};
+
+//#endregion
+//#region src/transform.ts
+function transform(s, ast, asyncImports, hasAwait) {
+	let declarationsEnd;
+	[s, declarationsEnd] = tansformAndMoveDeclarationsToModuleScope(s, ast, asyncImports);
+	s = s.appendRight(declarationsEnd, ";\nasync function __exec() {\n");
+	s = s.append("}\n");
+	const tlas = `[${asyncImports.map((_, i) => `__tla${i}`).join()}].flatMap(a => {
+        try {
+            const result = a();
+            if (Array.isArray(result)) {
+                return result
+            }
+            return [a];
+        } catch {
+            return []; // happens for cyclic dependencies
+        }
+    })`;
+	const execWrapper = asyncImports.length === 0 ? "__exec();" : `Promise.all(${tlas}.map(e => e())).then(() => __exec());`;
+	if (hasAwait) s = s.append(`const __tla = ${execWrapper}; const __todo = __tla;`);
+	else s = s.append(`const __tla = ${tlas};
+            const __todo = ${execWrapper};`);
+	s = s.append("if (import.meta.useTla) await __todo;");
+	s = s.append("export function __tla_access() { return __tla; };");
+	return s;
+}
+function tansformAndMoveDeclarationsToModuleScope(s, ast, asyncImports) {
+	let moduleScopeEnd = 0;
+	let i = 0;
+	for (const node of ast.body) {
+		if (asyncImports.includes(node)) {
+			const tlaImport = `;import { __tla_access as __tla${i}} from '${node.source.value}';`;
+			s = s.appendLeft(node.end, tlaImport);
+			i++;
+		}
+		if (node.type === "ExportNamedDeclaration") {
+			if (node.declaration?.type === "VariableDeclaration") {
+				s = s.appendLeft(moduleScopeEnd, ";export ");
+				s = s.remove(node.start, node.declaration.start);
+				s = moveVarDeclarationToModuleScope(s, node.declaration, moduleScopeEnd);
+			}
+		}
+		if (node.type === "VariableDeclaration") s = moveVarDeclarationToModuleScope(s, node, moduleScopeEnd);
+		if (isDeclaration(node.type) || node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" && isDeclaration(node.declaration?.type) || node.type === "ExportNamedDeclaration" && node.declaration == null || node.type === "ExportDefaultDeclaration" || node.type === "ExportAllDeclaration") if (node.start > moduleScopeEnd) {
+			s = s.appendRight(node.start, ";\n");
+			s = s.move(node.start, node.end, moduleScopeEnd);
+		} else moduleScopeEnd = node.end;
+	}
+	return [s, moduleScopeEnd];
+}
+function isDeclaration(type) {
+	return type === "ClassDeclaration" || type === "FunctionDeclaration";
+}
+function moveVarDeclarationToModuleScope(s, node, declarationsEnd) {
+	const kind = replaceConstWithLet(node.kind);
+	const names = node.declarations.flatMap((decl) => getNames(decl.id)).join(", ");
+	s = s.appendRight(node.declarations[0].start, "(");
+	s = s.appendLeft(node.declarations[node.declarations.length - 1].end, ")");
+	s = s.appendLeft(declarationsEnd, `\n${kind} ${names};\n`);
+	s = s.remove(node.start, node.declarations[0].start);
+	return s;
+}
+function replaceConstWithLet(value) {
+	if (value === "const") return "let";
+	return value;
+}
+function getNames(pattern) {
+	switch (pattern.type) {
+		case "Identifier": return [pattern.name];
+		case "MemberExpression": throw new Error("Unexpected member expression in variable declaration");
+		case "ObjectPattern": return pattern.properties.flatMap((p) => {
+			switch (p.type) {
+				case "Property": return getNames(p.value);
+				case "RestElement": return getNames(p.argument);
+			}
+		});
+		case "ArrayPattern": return pattern.elements.filter((e) => e != null).flatMap(getNames);
+		case "RestElement": return getNames(pattern.argument);
+		case "AssignmentPattern": return getNames(pattern.left);
+	}
+}
+
+//#endregion
+//#region src/index.ts
+function concurrentTopLevelAwait(options = {}) {
+	const filter = createFilter(options.include, options.exclude);
+	const asyncTree = new AsyncTlaTracker();
+	return {
+		name: "rollup-plugin-concurrent-tla-plugin",
+		apply: "build",
+		transform: { async handler(code, id) {
+			if (!filter(id)) return;
+			const ast = this.parse(code, { jsx: false });
+			const importDeclarations = ast.body.filter((a) => a.type === "ImportDeclaration");
+			const hasAwait = hasTopLevelAwait(ast);
+			if (hasAwait) asyncTree.setMarked(id, true);
+			else {
+				const childrenIds = (await Promise.all(importDeclarations.map(async (declaration) => {
+					const importId = await this.resolve(declaration.source.value, id);
+					if (!importId || !filter(importId.id)) return null;
+					return importId.id;
+				}))).filter((a) => a != null);
+				asyncTree.setChildren(id, childrenIds);
+			}
+			const asyncImports = (await Promise.all(importDeclarations.map(async (declaration) => {
+				const importId = await this.resolve(declaration.source.value, id);
+				if (!importId || !filter(importId.id)) return null;
+				this.load(importId);
+				if (!await asyncTree.get(importId.id)) return null;
+				return declaration;
+			}))).filter(Boolean);
+			const isAsyncModule = asyncImports.length > 0 || hasAwait;
+			if (!isAsyncModule) return;
+			let s = new MagicString(code);
+			s = transform(s, ast, asyncImports, hasAwait);
+			return {
+				code: s.toString(),
+				meta: { async: isAsyncModule }
+			};
+		} },
+		resolveImportMeta(property, { moduleId, chunkId }) {
+			if (property !== "useTla") return;
+			const moduleInfo = this.getModuleInfo(moduleId);
+			const importers = moduleInfo?.importers;
+			if (moduleInfo?.isEntry || !importers?.length) return "true";
+			if (importers.some((id) => !filter(id))) return "true";
+			return "false";
+		}
+	};
+}
+
+//#endregion
+export { concurrentTopLevelAwait as default };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "rollup-plugin-concurrent-top-level-await",
+  "version": "0.0.1",
+  "description": "Rollup (and Vite) plugin enabling concurrent execution of modules that contain top level await.",
+  "keywords": [
+    "rollup-plugin",
+    "vite-plugin",
+    "top-level-await",
+    "tla",
+    "concurrent",
+    "async",
+    "modules",
+    "es2022"
+  ],
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.mts",
+    "default": "./dist/index.mjs"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown --dts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zOadT/concurrent-top-level-await-plugins.git"
+  },
+  "author": "Oliver Zell",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/zOadT/concurrent-top-level-await-plugins/issues"
+  },
+  "homepage": "https://github.com/zOadT/concurrent-top-level-await-plugins/tree/main/packages/rollup-plugin#readme",
+  "peerDependencies": {
+    "rollup": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "rollup": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@rollup/pluginutils": "^5.3.0",
+    "magic-string": "^0.30.21"
+  },
+  "devDependencies": {
+    "@types/estree": "^1.0.8",
+    "prettier": "3.7.4"
+  }
+}