rollup-plugin-concurrent-top-level-await 0.2.1 → 0.3.0

package/README.md

@@ -8,6 +8,18 @@ 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).
 
+### Evaluation Order
+
+The evaluation order closely matches V8's behavior according to [tla-fuzzer](https://github.com/evanw/tla-fuzzer).
+Minor deviations can still occur though.
+
+| Variant                  | Rollup | Rollup with Plugin |
+| ------------------------ | ------ | ------------------ |
+| Simple                   | 80%    | 99%                |
+| Trailing Promise         | 10%    | 99%                |
+| Cyclic                   | 69%    | 99%                |
+| Cyclic, Trailing Promise | 15%    | 99%                |
+
 ## Installation
 
 Using npm:
@@ -41,7 +53,9 @@ export default {
 
 ### Which modules to include?
 
-The plugin needs to handle not only modules that directly contain a top-level `await`, but also their ancestor modules up to the lowest common ancestor. Ancestor modules must be transformed to handle the asynchronous completion of their children concurrently. As an example, consider the following module structure:
+The plugin needs to handle not only modules that directly contain a top-level `await`, but also their ancestor modules up to the lowest common ancestor. Ancestor modules must be transformed to handle the asynchronous completion of their children concurrently. If an ancestor module is not transformed, its direct dependencies will become blocking and therefore alter the evaluation order.
+
+Consider the following module structure as an example:
 
 ```mermaid
 flowchart LR
@@ -75,22 +89,11 @@ If the red modules contain top level awaits, these and their yellow ancestors sh
 
 ## 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%                |
+### Evaluation Order
 
-Please do not rely on a specific execution order when using this plugin.
+As can be seen in the table above, the plugin does not guarantee 100% matching of V8's evaluation order, although the deviations should be pretty minor in practice. If you encounter significant deviations, please open an issue.
 
-We might adapt Webpack's approach in the future to improve correctness.
+Additionally, some scenarios are known to cause deviations, e.g. when the [`include` option is not correctly configured](#which-modules-to-include) or when there is a dependency cycle that is split across multiple chunks.
 
 ### Build Performance
 

package/dist/index.d.mts

@@ -17,6 +17,8 @@ declare function concurrentTopLevelAwait(options?: {
 }): {
   name: string;
   apply: "build";
+  resolveId(this: rollup0.PluginContext, source: string): string | undefined;
+  load(this: rollup0.PluginContext, id: string): "export default function register(fn, evaluate_accesses) {\n    let state = \"ready\";\n    let whenDones = [];\n    let whenErrors = [];\n    let remaining = 1;\n    let error = undefined;\n    // evaluate eagerly\n    evaluate();\n\n    return evaluate;\n\n    function evaluate(whenDone, onError) {\n        if (state === \"done\") {\n            if (whenDone)\n                whenDone();\n            return;\n        }\n        if (state === \"failed\") {\n            if (onError)\n                onError(error);\n            return;\n        }\n        if (whenDone)\n            whenDones.push(whenDone);\n        if (onError)\n            whenErrors.push(onError);\n        if (state === \"busy\") {\n            return;\n        }\n        state = \"busy\";\n        let moduleDone = () => {\n            state = \"done\";\n            for (let x of whenDones)\n                x();\n        };\n        let moduleError = (err) => {\n            state = \"failed\";\n            error = err;\n            for (let x of whenErrors)\n                x(err);\n        };\n        let importDone = () => {\n            if (state !== \"busy\")\n                return;\n            if (--remaining !== 0)\n                return;\n            try {\n                let result = fn();\n                if (result) {\n                    result\n                        .then(moduleDone)\n                        .catch(moduleError);\n                }\n                else {\n                    moduleDone();\n                }\n            }\n            catch (err) {\n                moduleError(err);\n            }\n        };\n        for (const access of evaluate_accesses) {\n            let evaluate;\n            try {\n                // Environment-dependent behavior:\n                // - throws on cyclic dependencies in V8\n                // - returns undefined in some environments (e.g., vitest)\n                evaluate = access();\n                if (evaluate == null)\n                    continue;\n            }\n            catch (_a) {\n                continue;\n            }\n            remaining++;\n            evaluate(importDone, moduleError);\n        }\n        importDone();\n    }\n}\n" | undefined;
   transform: {
     handler(this: TransformPluginContext, code: string, id: string, transformOptions: {
       ssr?: boolean | undefined;

package/dist/index.mjs

@@ -128,26 +128,14 @@ var AsyncModuleTracker = class {
 
 //#endregion
 //#region src/transform.ts
-function transform(s, ast, asyncImports, hasAwait, variablePrefix) {
+function transform(s, ast, registerModuleSource, asyncImports, hasAwait, variablePrefix) {
 	const declarationsEnd = transformAndMoveDeclarationsToModuleScope(s, ast, asyncImports, variablePrefix);
-	s.appendRight(declarationsEnd, `async function ${variablePrefix}_initModuleExports() {\n`);
+	s.appendRight(declarationsEnd, `${hasAwait ? "async " : ""}function ${variablePrefix}_initModuleExports() {\n`);
 	s.append("\n}\n");
-	const asyncDeps = `[${asyncImports.map((_, i) => `${variablePrefix}${i}`).join()}].flatMap(a => {
-	try {
-		const result = a();
-		if (Array.isArray(result)) {
-			return result
-		}
-		return [a];
-	} catch {
-		return []; // happens for cyclic dependencies
-	}
-})`;
-	const initModuleExportsAfterDeps = asyncImports.length === 0 ? `${variablePrefix}_initModuleExports()` : `Promise.all(${asyncDeps}.map(e => e())).then(() => ${variablePrefix}_initModuleExports())`;
-	if (hasAwait) s.append(`const ${variablePrefix} = ${initModuleExportsAfterDeps};\nconst ${variablePrefix}_initPromise = ${variablePrefix};\n`);
-	else s.append(`const ${variablePrefix} = ${asyncDeps};\nconst ${variablePrefix}_initPromise = ${initModuleExportsAfterDeps};\n`);
-	s.append(`if (import.meta.useTla) await ${variablePrefix}_initPromise;\n`);
-	s.append(`export function ${variablePrefix}_access() { return ${variablePrefix}; };\n`);
+	s.prepend(`import ${variablePrefix}_register from ${JSON.stringify(registerModuleSource)};\n`);
+	const asyncDeps = `[${asyncImports.map((_, i) => `() => ${variablePrefix}${i}`).join(", ")}]`;
+	s.append(`export const ${variablePrefix}_access = ${variablePrefix}_register(${variablePrefix}_initModuleExports, ${asyncDeps});\n`);
+	s.append(`if (import.meta.useTla) await new Promise(${variablePrefix}_access);\n`);
 }
 function transformAndMoveDeclarationsToModuleScope(s, ast, asyncImports, variablePrefix) {
 	let moduleScopeEnd = 0;
@@ -250,12 +238,100 @@ function resolveDeclarationSource(context, id, importerAttributes = {}, declarat
 		custom: {}
 	});
 }
+const tlaModule = `export default function register(fn, evaluate_accesses) {
+    let state = "ready";
+    let whenDones = [];
+    let whenErrors = [];
+    let remaining = 1;
+    let error = undefined;
+    // evaluate eagerly
+    evaluate();
+
+    return evaluate;
+
+    function evaluate(whenDone, onError) {
+        if (state === "done") {
+            if (whenDone)
+                whenDone();
+            return;
+        }
+        if (state === "failed") {
+            if (onError)
+                onError(error);
+            return;
+        }
+        if (whenDone)
+            whenDones.push(whenDone);
+        if (onError)
+            whenErrors.push(onError);
+        if (state === "busy") {
+            return;
+        }
+        state = "busy";
+        let moduleDone = () => {
+            state = "done";
+            for (let x of whenDones)
+                x();
+        };
+        let moduleError = (err) => {
+            state = "failed";
+            error = err;
+            for (let x of whenErrors)
+                x(err);
+        };
+        let importDone = () => {
+            if (state !== "busy")
+                return;
+            if (--remaining !== 0)
+                return;
+            try {
+                let result = fn();
+                if (result) {
+                    result
+                        .then(moduleDone)
+                        .catch(moduleError);
+                }
+                else {
+                    moduleDone();
+                }
+            }
+            catch (err) {
+                moduleError(err);
+            }
+        };
+        for (const access of evaluate_accesses) {
+            let evaluate;
+            try {
+                // Environment-dependent behavior:
+                // - throws on cyclic dependencies in V8
+                // - returns undefined in some environments (e.g., vitest)
+                evaluate = access();
+                if (evaluate == null)
+                    continue;
+            }
+            catch (_a) {
+                continue;
+            }
+            remaining++;
+            evaluate(importDone, moduleError);
+        }
+        importDone();
+    }
+}
+`;
 function concurrentTopLevelAwait(options = {}) {
 	const filter = createFilter(options.include, options.exclude);
+	const registerModuleSource = `\0${options.generatedVariablePrefix ?? "__tla"}Register`;
 	const asyncTracker = new AsyncModuleTracker();
 	return {
 		name: "rollup-plugin-concurrent-tla-plugin",
 		apply: "build",
+		resolveId(source) {
+			if (source === registerModuleSource) return registerModuleSource;
+		},
+		load(id) {
+			if (id === registerModuleSource) return tlaModule;
+		},
 		transform: { async handler(code, id, transformOptions) {
 			if (!filter(id)) return;
 			const ast = this.parse(code);
@@ -263,24 +339,23 @@ function concurrentTopLevelAwait(options = {}) {
 			const hasAwait = hasTopLevelAwait(ast);
 			asyncTracker.setEntryAsync(id, hasAwait);
 			if (hasAwait) asyncTracker.setDependencies(id, []);
-			else {
-				const childrenIds = (await Promise.all(importDeclarations.map(async (declaration) => {
-					const importId = await resolveDeclarationSource(this, id, transformOptions?.attributes, declaration);
-					if (!importId || !filter(importId.id)) return null;
-					return importId.id;
-				}))).filter((a) => a != null);
-				asyncTracker.setDependencies(id, childrenIds);
-			}
-			const asyncImports = (await Promise.all(importDeclarations.map(async (declaration) => {
+			let imports = (await Promise.all(importDeclarations.map(async (declaration) => {
 				const importId = await resolveDeclarationSource(this, id, transformOptions?.attributes, declaration);
 				if (!importId || !filter(importId.id)) return null;
-				this.load(importId);
-				if (!await asyncTracker.isAsync(importId.id)) return null;
+				return {
+					declaration,
+					id: importId.id
+				};
+			}))).filter(Boolean);
+			if (!hasAwait) asyncTracker.setDependencies(id, imports.map((x) => x.id));
+			const asyncImports = (await Promise.all(imports.map(async ({ declaration, id: id$1 }) => {
+				this.load({ id: id$1 });
+				if (!await asyncTracker.isAsync(id$1)) return null;
 				return declaration;
 			}))).filter(Boolean);
 			if (!(asyncImports.length > 0 || hasAwait)) return;
 			const s = new MagicString(code);
-			transform(s, ast, asyncImports, hasAwait, options.generatedVariablePrefix ?? "__tla");
+			transform(s, ast, registerModuleSource, asyncImports, hasAwait, options.generatedVariablePrefix ?? "__tla");
 			return {
 				code: s.toString(),
 				map: options.sourceMap !== false ? s.generateMap({ hires: true }) : null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rollup-plugin-concurrent-top-level-await",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Rollup (and Vite) plugin enabling concurrent execution of modules that contain top level await.",
   "keywords": [
     "rollup-plugin",