feat: link top-level using declarations in components to lifecycle

Author: Rich-Harris

.changeset/nasty-hotels-clap.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: link top-level `using` declarations in components to lifecycle

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -472,7 +472,8 @@ export function analyze_component(root, source, options) {
 		source,
 		undefined_exports: new Map(),
 		snippet_renderers: new Map(),
-		snippets: new Set()
+		snippets: new Set(),
+		disposable: []
 	};
 
 	if (!runes) {

packages/svelte/src/compiler/phases/3-transform/client/transform-client.js

@@ -362,6 +362,10 @@ export function client_component(analysis, options) {
 		.../** @type {ESTree.Statement[]} */ (template.body)
 	]);
 
+	if (analysis.disposable.length > 0) {
+		component_block.body.push(b.stmt(b.call('$.dispose', ...analysis.disposable)));
+	}
+
 	if (!analysis.runes) {
 		// Bind static exports to props so that people can access them with bind:x
 		for (const { name, alias } of analysis.exports) {

packages/svelte/src/compiler/phases/3-transform/client/visitors/VariableDeclaration.js

@@ -16,7 +16,7 @@ import { get_value } from './shared/declarations.js';
  */
 export function VariableDeclaration(node, context) {
 	/** @type {VariableDeclarator[]} */
-	const declarations = [];
+	let declarations = [];
 
 	if (context.state.analysis.runes) {
 		for (const declarator of node.declarations) {
@@ -343,8 +343,27 @@ export function VariableDeclaration(node, context) {
 		return b.empty;
 	}
 
+	let kind = node.kind;
+
+	// @ts-expect-error
+	if (kind === 'using' && context.state.is_instance && context.path.length === 1) {
+		context.state.analysis.disposable.push(
+			...node.declarations.map((declarator) => /** @type {Identifier} */ (declarator.id))
+		);
+
+		if (dev) {
+			declarations = declarations.map((declarator) => ({
+				...declarator,
+				init: b.call('$.disposable', /** @type {Expression} */ (declarator.init))
+			}));
+		}
+
+		kind = 'const';
+	}
+
 	return {
 		...node,
+		kind,
 		declarations
 	};
 }

packages/svelte/src/compiler/phases/types.d.ts

@@ -100,6 +100,10 @@ export interface ComponentAnalysis extends Analysis {
 	 * Every snippet that is declared locally
 	 */
 	snippets: Set<AST.SnippetBlock>;
+	/**
+	 * An array of any `using` declarations
+	 */
+	disposable: Identifier[];
 }
 
 declare module 'estree' {

packages/svelte/src/internal/client/index.js

@@ -118,6 +118,7 @@ export {
 	update_pre_prop,
 	update_prop
 } from './reactivity/props.js';
+export { dispose, disposable } from './resource-management/index.js';
 export {
 	invalidate_store,
 	store_mutate,

packages/svelte/src/internal/client/resource-management/index.js

@@ -0,0 +1,26 @@
+import { teardown } from '../reactivity/effects.js';
+
+/**
+ * @param  {...any} disposables
+ */
+export function dispose(...disposables) {
+	teardown(() => {
+		for (const disposable of disposables) {
+			disposable?.[Symbol.dispose]();
+		}
+	});
+}
+
+/**
+ * In dev, check that a value used with `using` is in fact disposable. We need this
+ * because we're replacing `using foo = ...` with `const foo = ...` if the
+ * declaration is at the top level of a component
+ * @param {any} value
+ */
+export function disposable(value) {
+	if (value != null && !value[Symbol.dispose]) {
+		throw new TypeError('Symbol(Symbol.dispose) is not a function');
+	}
+
+	return value;
+}

packages/svelte/tests/runtime-runes/samples/using-top-level/Child.svelte

@@ -0,0 +1,12 @@
+<script>
+	let { message } = $props();
+
+	using x = {
+		message,
+		[Symbol.dispose]() {
+			console.log(`disposing ${message}`);
+		}
+	}
+</script>
+
+<p>{x.message}</p>

packages/svelte/tests/runtime-runes/samples/using-top-level/_config.js

@@ -0,0 +1,18 @@
+import { flushSync } from 'svelte';
+import { test } from '../../test';
+
+export default test({
+	// TODO unskip this for applicable node versions, once supported
+	skip: true,
+
+	html: `<button>toggle</button><p>hello</p>`,
+
+	test({ assert, target, logs }) {
+		const [button] = target.querySelectorAll('button');
+
+		flushSync(() => button.click());
+		assert.htmlEqual(target.innerHTML, `<button>toggle</button>`);
+
+		assert.deepEqual(logs, ['disposing hello']);
+	}
+});

packages/svelte/tests/runtime-runes/samples/using-top-level/main.svelte

@@ -0,0 +1,13 @@
+<script>
+	import Child from './Child.svelte';
+
+	let message = $state('hello');
+</script>
+
+<button onclick={() => message = message ? null : 'hello'}>
+	toggle
+</button>
+
+{#if message}
+	<Child {message} />
+{/if}