feat: allow await in components

.changeset/eleven-weeks-dance.md

@@ -0,0 +1,5 @@
+---
+'svelte': minor
+---
+
+feat: support `await` in components

documentation/docs/98-reference/.generated/client-warnings.md

@@ -34,6 +34,22 @@ function add() {
 }
 ```
 
+### await_reactivity_loss
+
+```
+Detected reactivity loss
+```
+
+TODO
+
+### await_waterfall
+
+```
+An async value (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app.
+```
+
+TODO
+
 ### binding_property_non_reactive
 
 ```

documentation/docs/98-reference/.generated/compile-errors.md

@@ -480,6 +480,12 @@ Expected token %token%
 Expected whitespace
 ```
 
+### experimental_async
+
+```
+Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+```
+
 ### export_undefined
 
 ```
@@ -534,6 +540,12 @@ The arguments keyword cannot be used within the template or at the top level of
 %message%
 ```
 
+### legacy_await_invalid
+
+```
+Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+```
+
 ### legacy_export_invalid
 
 ```

documentation/docs/98-reference/.generated/shared-errors.md

@@ -1,5 +1,13 @@
 <!-- This file is generated by scripts/process-messages/index.js. Do not edit! -->
 
+### await_outside_boundary
+
+```
+Cannot await outside a `<svelte:boundary>` with a `pending` snippet
+```
+
+TODO
+
 ### invalid_default_snippet
 
 ```

packages/svelte/messages/client-warnings/warnings.md

@@ -30,6 +30,18 @@ function add() {
 }
 ```
 
+## await_reactivity_loss
+
+> Detected reactivity loss
+
+TODO
+
+## await_waterfall
+
+> An async value (%location%) was not read immediately after it resolved. This often indicates an unnecessary waterfall, which can slow down your app.
+
+TODO
+
 ## binding_property_non_reactive
 
 > `%binding%` is binding to a non-reactive property

packages/svelte/messages/compile-errors/script.md

@@ -70,6 +70,10 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 > `$effect()` can only be used as an expression statement
 
+## experimental_async
+
+> Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+
 ## export_undefined
 
 > `%name%` is not defined
@@ -98,6 +102,10 @@ This turned out to be buggy and unpredictable, particularly when working with de
 
 > The arguments keyword cannot be used within the template or at the top level of a component
 
+## legacy_await_invalid
+
+> Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+
 ## legacy_export_invalid
 
 > Cannot use `export let` in runes mode — use `$props()` instead

packages/svelte/messages/shared-errors/errors.md

@@ -1,3 +1,9 @@
+## await_outside_boundary
+
+> Cannot await outside a `<svelte:boundary>` with a `pending` snippet
+
+TODO
+
 ## invalid_default_snippet
 
 > Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead

packages/svelte/src/compiler/errors.js

@@ -168,6 +168,15 @@ export function effect_invalid_placement(node) {
 	e(node, 'effect_invalid_placement', `\`$effect()\` can only be used as an expression statement\nhttps://svelte.dev/e/effect_invalid_placement`);
 }
 
+/**
+ * Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless the `experimental.async` compiler option is `true`
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function experimental_async(node) {
+	e(node, 'experimental_async', `Cannot use \`await\` in deriveds and template expressions, or at the top level of a component, unless the \`experimental.async\` compiler option is \`true\`\nhttps://svelte.dev/e/experimental_async`);
+}
+
 /**
  * `%name%` is not defined
  * @param {null | number | NodeLike} node
@@ -233,6 +242,15 @@ export function invalid_arguments_usage(node) {
 	e(node, 'invalid_arguments_usage', `The arguments keyword cannot be used within the template or at the top level of a component\nhttps://svelte.dev/e/invalid_arguments_usage`);
 }
 
+/**
+ * Cannot use `await` in deriveds and template expressions, or at the top level of a component, unless in runes mode
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function legacy_await_invalid(node) {
+	e(node, 'legacy_await_invalid', `Cannot use \`await\` in deriveds and template expressions, or at the top level of a component, unless in runes mode\nhttps://svelte.dev/e/legacy_await_invalid`);
+}
+
 /**
  * Cannot use `export let` in runes mode — use `$props()` instead
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/migrate/index.js

@@ -146,7 +146,10 @@ export function migrate(source, { filename, use_ts } = {}) {
 			...validate_component_options({}, ''),
 			...parsed_options,
 			customElementOptions,
-			filename: filename ?? '(unknown)'
+			filename: filename ?? '(unknown)',
+			experimental: {
+				async: true
+			}
 		};
 
 		const str = new MagicString(source);

packages/svelte/src/compiler/phases/1-parse/state/element.js

@@ -295,6 +295,8 @@ export default function element(parser) {
 		} else {
 			element.tag = get_attribute_expression(definition);
 		}
+
+		element.metadata.expression = create_expression_metadata();
 	}
 
 	if (is_top_level_script_or_style) {

packages/svelte/src/compiler/phases/1-parse/state/tag.js

@@ -63,7 +63,10 @@ function open(parser) {
 			end: -1,
 			test: read_expression(parser),
 			consequent: create_fragment(),
-			alternate: null
+			alternate: null,
+			metadata: {
+				expression: create_expression_metadata()
+			}
 		});
 
 		parser.allow_whitespace();
@@ -326,7 +329,10 @@ function open(parser) {
 			start,
 			end: -1,
 			expression,
-			fragment: create_fragment()
+			fragment: create_fragment(),
+			metadata: {
+				expression: create_expression_metadata()
+			}
 		});
 
 		parser.stack.push(block);
@@ -461,7 +467,10 @@ function next(parser) {
 				elseif: true,
 				test: expression,
 				consequent: create_fragment(),
-				alternate: null
+				alternate: null,
+				metadata: {
+					expression: create_expression_metadata()
+				}
 			});
 
 			parser.stack.push(child);
@@ -624,7 +633,10 @@ function special(parser) {
 			type: 'HtmlTag',
 			start,
 			end: parser.index,
-			expression
+			expression,
+			metadata: {
+				expression: create_expression_metadata()
+			}
 		});
 
 		return;

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

@@ -21,6 +21,7 @@ import { AssignmentExpression } from './visitors/AssignmentExpression.js';
 import { AttachTag } from './visitors/AttachTag.js';
 import { Attribute } from './visitors/Attribute.js';
 import { AwaitBlock } from './visitors/AwaitBlock.js';
+import { AwaitExpression } from './visitors/AwaitExpression.js';
 import { BindDirective } from './visitors/BindDirective.js';
 import { CallExpression } from './visitors/CallExpression.js';
 import { ClassBody } from './visitors/ClassBody.js';
@@ -138,6 +139,7 @@ const visitors = {
 	AttachTag,
 	Attribute,
 	AwaitBlock,
+	AwaitExpression,
 	BindDirective,
 	CallExpression,
 	ClassBody,
@@ -209,9 +211,14 @@ function js(script, root, allow_reactive_declarations, parent) {
 		body: []
 	};
 
-	const { scope, scopes } = create_scopes(ast, root, allow_reactive_declarations, parent);
+	const { scope, scopes, has_await } = create_scopes(
+		ast,
+		root,
+		allow_reactive_declarations,
+		parent
+	);
 
-	return { ast, scope, scopes };
+	return { ast, scope, scopes, has_await };
 }
 
 /**
@@ -236,7 +243,7 @@ const RESERVED = ['$$props', '$$restProps', '$$slots'];
  * @returns {Analysis}
  */
 export function analyze_module(ast, options) {
-	const { scope, scopes } = create_scopes(ast, new ScopeRoot(), false, null);
+	const { scope, scopes, has_await } = create_scopes(ast, new ScopeRoot(), false, null);
 
 	for (const [name, references] of scope.references) {
 		if (name[0] !== '$' || RESERVED.includes(name)) continue;
@@ -253,12 +260,14 @@ export function analyze_module(ast, options) {
 
 	/** @type {Analysis} */
 	const analysis = {
-		module: { ast, scope, scopes },
+		module: { ast, scope, scopes, has_await },
 		name: options.filename,
 		accessors: false,
 		runes: true,
 		immutable: true,
 		tracing: false,
+		async_deriveds: new Set(),
+		context_preserving_awaits: new Set(),
 		classes: new Map()
 	};
 
@@ -298,7 +307,12 @@ export function analyze_component(root, source, options) {
 	const module = js(root.module, scope_root, false, null);
 	const instance = js(root.instance, scope_root, true, module.scope);
 
-	const { scope, scopes } = create_scopes(root.fragment, scope_root, false, instance.scope);
+	const { scope, scopes, has_await } = create_scopes(
+		root.fragment,
+		scope_root,
+		false,
+		instance.scope
+	);
 
 	/** @type {Template} */
 	const template = { ast: root.fragment, scope, scopes };
@@ -406,7 +420,9 @@ export function analyze_component(root, source, options) {
 
 	const component_name = get_component_name(options.filename);
 
-	const runes = options.runes ?? Array.from(module.scope.references.keys()).some(is_rune);
+	const runes =
+		options.runes ??
+		(has_await || instance.has_await || Array.from(module.scope.references.keys()).some(is_rune));
 
 	if (!runes) {
 		for (let check of synthetic_stores_legacy_check) {
@@ -472,7 +488,9 @@ export function analyze_component(root, source, options) {
 		source,
 		undefined_exports: new Map(),
 		snippet_renderers: new Map(),
-		snippets: new Set()
+		snippets: new Set(),
+		async_deriveds: new Set(),
+		context_preserving_awaits: new Set()
 	};
 
 	if (!runes) {

packages/svelte/src/compiler/phases/2-analyze/visitors/AwaitExpression.js

@@ -0,0 +1,50 @@
+/** @import { AwaitExpression } from 'estree' */
+/** @import { Context } from '../types' */
+import * as e from '../../../errors.js';
+
+/**
+ * @param {AwaitExpression} node
+ * @param {Context} context
+ */
+export function AwaitExpression(node, context) {
+	const tla = context.state.ast_type === 'instance' && context.state.function_depth === 1;
+	let suspend = tla;
+	let preserve_context = tla;
+
+	if (context.state.expression) {
+		context.state.expression.has_await = true;
+		suspend = true;
+
+		// wrap the expression in `(await $.save(...)).restore()` if necessary,
+		// i.e. whether anything could potentially be read _after_ the await
+		let i = context.path.length;
+		while (i--) {
+			const parent = context.path[i];
+
+			// stop walking up when we find a node with metadata, because that
+			// means we've hit the template node containing the expression
+			// @ts-expect-error we could probably use a neater/more robust mechanism
+			if (parent.metadata) break;
+
+			// TODO make this more accurate — we don't need to call suspend
+			// if this is the last thing that could be read
+			preserve_context = true;
+		}
+	}
+
+	if (suspend) {
+		if (!context.state.options.experimental.async) {
+			e.experimental_async(node);
+		}
+
+		if (!context.state.analysis.runes) {
+			e.legacy_await_invalid(node);
+		}
+	}
+
+	if (preserve_context) {
+		context.state.analysis.context_preserving_awaits.add(node);
+	}
+
+	context.next();
+}