feat: support using for RollupBuild (#5721)

* feat: support using for RollupBuild

* chore: follow the suggestions

* chore: add test case

* chore: add docs

cli/run/build.ts

@@ -30,7 +30,7 @@ export default async function build(
 		stderr(cyan(`\n${bold(inputFiles!)} → ${bold(files.join(', '))}...`));
 	}
 
-	const bundle = await rollup(inputOptions as any);
+	await using bundle = await rollup(inputOptions as any);
 	if (useStdout) {
 		const output = outputOptions[0];
 		if (output.sourcemap && output.sourcemap !== 'inline') {
@@ -48,7 +48,6 @@ export default async function build(
 	}
 
 	await Promise.all(outputOptions.map(bundle.write));
-	await bundle.close();
 	if (!silent) {
 		warnings.flush();
 		stderr(green(`created ${bold(files.join(', '))} in ${bold(ms(Date.now() - start))}`));

docs/javascript-api/index.md

@@ -53,7 +53,12 @@ async function build() {
 	let bundle;
 	let buildFailed = false;
 	try {
-		// create a bundle
+		// Create a bundle. If you are using TypeScript or a runtime that
+		// supports it, you can write
+		//
+		// await using bundle = await rollup(inputOptions);
+		//
+		// instead and do not need to close the bundle explicitly below.
 		bundle = await rollup(inputOptions);
 
 		// an array of file names this bundle depends on

src/rollup/rollup.ts

@@ -38,6 +38,9 @@ import type {
 	RollupWatcher
 } from './types';
 
+// @ts-expect-error TS2540: the polyfill of `asyncDispose`.
+Symbol.asyncDispose ??= Symbol('Symbol.asyncDispose');
+
 export default function rollup(rawInputOptions: RollupOptions): Promise<RollupBuild> {
 	return rollupInternal(rawInputOptions, null);
 }
@@ -95,6 +98,9 @@ export async function rollupInternal(
 			await graph.pluginDriver.hookParallel('closeBundle', []);
 		},
 		closed: false,
+		async [Symbol.asyncDispose]() {
+			await this.close();
+		},
 		async generate(rawOutputOptions: OutputOptions) {
 			if (result.closed) return error(logAlreadyClosed());
 

src/rollup/types.d.ts

@@ -918,6 +918,7 @@ export interface RollupBuild {
 	cache: RollupCache | undefined;
 	close: () => Promise<void>;
 	closed: boolean;
+	[Symbol.asyncDispose](): Promise<void>;
 	generate: (outputOptions: OutputOptions) => Promise<RollupOutput>;
 	getTimings?: () => SerializedTimings;
 	watchFiles: string[];

test/misc/misc.js

@@ -318,4 +318,18 @@ console.log(x);
 		await bundle.generate({ format: 'iife', inlineDynamicImports: true });
 		await bundle.generate({ format: 'es', exports: 'auto' });
 	});
+
+	it('should support `Symbol.asyncDispose` of the rollup bundle and set closed state to true', async () => {
+		const bundle = await rollup.rollup({
+			input: 'main.js',
+			plugins: [
+				loader({
+					'main.js': "console.log('hello')"
+				})
+			]
+		});
+
+		await bundle[Symbol.asyncDispose]();
+		assert.strictEqual(bundle.closed, true);
+	});
 });

tsconfig.json

@@ -2,6 +2,7 @@
 	"compilerOptions": {
 		"allowSyntheticDefaultImports": true,
 		"forceConsistentCasingInFileNames": true,
+		"lib": ["ES2022", "ESNext.Disposable", "DOM"],
 		"module": "ESNext",
 		"moduleResolution": "Bundler",
 		"noEmitOnError": true,