feat: hydratable and friends

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

@@ -130,12 +130,6 @@ $effect(() => {
 
 Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency.
 
-### experimental_async_fork
-
-```
-Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
-```
-
 ### flush_sync_in_effect
 
 ```
@@ -146,6 +140,12 @@ The `flushSync()` function can be used to flush any pending effects synchronousl
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+### fn_unavailable_on_client
+
+```
+`%name%`(...) is unavailable on the client.
+```
+
 ### fork_discarded
 
 ```

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

@@ -140,6 +140,25 @@ The easiest way to log a value as it changes over time is to use the [`$inspect`
 %handler% should be a function. Did you mean to %suggestion%?
 ```
 
+### hydratable_missing_but_expected
+
+```
+Expected to find a hydratable with key `%key%` during hydration, but did not.
+```
+
+This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes.
+
+```svelte
+<script>
+  import { hydratable } from 'svelte';
+
+	if (BROWSER) {
+		// bad! nothing can become interactive until this asynchronous work is done
+		await hydratable('foo', get_slow_random_number);
+	}
+</script>
+```
+
 ### hydration_attribute_changed
 
 ```

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

@@ -8,16 +8,52 @@ Encountered asynchronous work while rendering synchronously.
 
 You (or the framework you're using) called [`render(...)`](svelte-server#render) with a component containing an `await` expression. Either `await` the result of `render` or wrap the `await` (or the component containing it) in a [`<svelte:boundary>`](svelte-boundary) with a `pending` snippet.
 
+### fn_unavailable_on_server
+
+```
+`%name%`(...) is unavailable on the server.
+```
+
 ### html_deprecated
 
 ```
 The `html` property of server render results has been deprecated. Use `body` instead.
 ```
 
+### hydratable_clobbering
+
+```
+Attempted to set hydratable with key `%key%` twice. This behavior is undefined.
+
+First set occurred at:
+%stack%
+```
+
+This error occurs when using `hydratable` or `setHydratableValue` multiple times with the same key. To avoid this, you can combine `hydratable` with `cache`, or check whether the value has already been set with `hasHydratableValue`.
+
+```svelte
+<script>
+  import { hydratable } from 'svelte';
+
+  await Promise.all([
+    // which one should "win" and be serialized in the rendered response?
+    hydratable('hello', () => 'world'),
+    hydratable('hello', () => 'dad')
+  ])
+</script>
+```
+
 ### lifecycle_function_unavailable
 
 ```
 `%name%(...)` is not available on the server
+Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render.
 ```
 
-Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render.
+### render_context_unavailable
+
+```
+Failed to retrieve `render` context. %addendum%
+```
+
+If `AsyncLocalStorage` is available, you're likely calling a function that needs access to the `render` context (`hydratable`, `cache`, or something that depends on these) from outside of `render`. If `AsyncLocalStorage` is not available, these functions must also be called synchronously from within `render` -- i.e. not after any `await`s.

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

@@ -1,5 +1,11 @@
 <!-- This file is generated by scripts/process-messages/index.js. Do not edit! -->
 
+### experimental_async_required
+
+```
+Cannot use `%name%(...)` unless the `experimental.async` compiler option is `true`
+```
+
 ### invalid_default_snippet
 
 ```

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

@@ -100,10 +100,6 @@ $effect(() => {
 
 Often when encountering this issue, the value in question shouldn't be state (for example, if you are pushing to a `logs` array in an effect, make `logs` a normal array rather than `$state([])`). In the rare cases where you really _do_ need to write to state in an effect — [which you should avoid]($effect#When-not-to-use-$effect) — you can read the state with [untrack](svelte#untrack) to avoid adding it as a dependency.
 
-## experimental_async_fork
-
-> Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
-
 ## flush_sync_in_effect
 
 > Cannot use `flushSync` inside an effect
@@ -112,6 +108,10 @@ The `flushSync()` function can be used to flush any pending effects synchronousl
 
 This restriction only applies when using the `experimental.async` option, which will be active by default in Svelte 6.
 
+## fn_unavailable_on_client
+
+> `%name%`(...) is unavailable in the browser.
+
 ## fork_discarded
 
 > Cannot commit a fork that was already discarded

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

@@ -124,6 +124,23 @@ The easiest way to log a value as it changes over time is to use the [`$inspect`
 
 > %handler% should be a function. Did you mean to %suggestion%?
 
+## hydratable_missing_but_expected
+
+> Expected to find a hydratable with key `%key%` during hydration, but did not.
+
+This can happen if you render a hydratable on the client that was not rendered on the server, and means that it was forced to fall back to running its function blockingly during hydration. This is bad for performance, as it blocks hydration until the asynchronous work completes.
+
+```svelte
+<script>
+  import { hydratable } from 'svelte';
+
+	if (BROWSER) {
+		// bad! nothing can become interactive until this asynchronous work is done
+		await hydratable('foo', get_slow_random_number);
+	}
+</script>
+```
+
 ## hydration_attribute_changed
 
 > The `%attribute%` attribute on `%html%` changed its value between server and client renders. The client value, `%value%`, will be ignored in favour of the server value

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

@@ -4,12 +4,42 @@
 
 You (or the framework you're using) called [`render(...)`](svelte-server#render) with a component containing an `await` expression. Either `await` the result of `render` or wrap the `await` (or the component containing it) in a [`<svelte:boundary>`](svelte-boundary) with a `pending` snippet.
 
+## fn_unavailable_on_server
+
+> `%name%`(...) is unavailable on the server.
+
 ## html_deprecated
 
 > The `html` property of server render results has been deprecated. Use `body` instead.
 
+## hydratable_clobbering
+
+> Attempted to set hydratable with key `%key%` twice. This behavior is undefined.
+>
+> First set occurred at:
+> %stack%
+
+This error occurs when using `hydratable` or `hydratable.set` multiple times with the same key. To avoid this, you can combine `hydratable` with `cache`, or check whether the value has already been set with `hydratable.has`.
+
+```svelte
+<script>
+  import { hydratable } from 'svelte';
+
+  await Promise.all([
+    // which one should "win" and be serialized in the rendered response?
+    hydratable('hello', () => 'world'),
+    hydratable('hello', () => 'dad')
+  ])
+</script>
+```
+
 ## lifecycle_function_unavailable
 
 > `%name%(...)` is not available on the server
-
 Certain methods such as `mount` cannot be invoked while running in a server context. Avoid calling them eagerly, i.e. not during render.
+
+## render_context_unavailable
+
+> Failed to retrieve `render` context. %addendum%
+
+If `AsyncLocalStorage` is available, you're likely calling a function that needs access to the `render` context (`hydratable`, `cache`, or something that depends on these) from outside of `render`. If `AsyncLocalStorage` is not available, these functions must also be called synchronously from within `render` -- i.e. not after any `await`s.

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

@@ -1,3 +1,7 @@
+## experimental_async_required
+
+> Cannot use `%name%(...)` unless the `experimental.async` compiler option is `true`
+
 ## invalid_default_snippet
 
 > Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead

packages/svelte/package.json

@@ -174,6 +174,7 @@
     "aria-query": "^5.3.1",
     "axobject-query": "^4.1.0",
     "clsx": "^2.1.1",
+    "devalue": "^5.4.1",
     "esm-env": "^1.2.1",
     "esrap": "^2.1.0",
     "is-reference": "^3.0.3",

packages/svelte/src/index-client.js

@@ -249,6 +249,7 @@ export {
 	hasContext,
 	setContext
 } from './internal/client/context.js';
+export { hydratable } from './internal/client/hydratable.js';
 export { hydrate, mount, unmount } from './internal/client/render.js';
 export { tick, untrack, settled } from './internal/client/runtime.js';
 export { createRawSnippet } from './internal/client/dom/blocks/snippet.js';

packages/svelte/src/index-server.js

@@ -51,4 +51,6 @@ export {
 	setContext
 } from './internal/server/context.js';
 
+export { hydratable } from './internal/server/hydratable.js';
+
 export { createRawSnippet } from './internal/server/blocks/snippet.js';

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

@@ -5,7 +5,7 @@ import { active_effect, active_reaction } from './runtime.js';
 import { create_user_effect } from './reactivity/effects.js';
 import { async_mode_flag, legacy_mode_flag } from '../flags/index.js';
 import { FILENAME } from '../../constants.js';
-import { BRANCH_EFFECT, EFFECT_RAN } from './constants.js';
+import { BRANCH_EFFECT } from './constants.js';
 
 /** @type {ComponentContext | null} */
 export let component_context = null;

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

@@ -230,34 +230,35 @@ export function effect_update_depth_exceeded() {
 }
 
 /**
- * Cannot use `fork(...)` unless the `experimental.async` compiler option is `true`
+ * Cannot use `flushSync` inside an effect
  * @returns {never}
  */
-export function experimental_async_fork() {
+export function flush_sync_in_effect() {
 	if (DEV) {
-		const error = new Error(`experimental_async_fork\nCannot use \`fork(...)\` unless the \`experimental.async\` compiler option is \`true\`\nhttps://svelte.dev/e/experimental_async_fork`);
+		const error = new Error(`flush_sync_in_effect\nCannot use \`flushSync\` inside an effect\nhttps://svelte.dev/e/flush_sync_in_effect`);
 
 		error.name = 'Svelte error';
 
 		throw error;
 	} else {
-		throw new Error(`https://svelte.dev/e/experimental_async_fork`);
+		throw new Error(`https://svelte.dev/e/flush_sync_in_effect`);
 	}
 }
 
 /**
- * Cannot use `flushSync` inside an effect
+ * `%name%`(...) is unavailable on the client.
+ * @param {string} name
  * @returns {never}
  */
-export function flush_sync_in_effect() {
+export function fn_unavailable_on_client(name) {
 	if (DEV) {
-		const error = new Error(`flush_sync_in_effect\nCannot use \`flushSync\` inside an effect\nhttps://svelte.dev/e/flush_sync_in_effect`);
+		const error = new Error(`fn_unavailable_on_client\n\`${name}\`(...) is unavailable on the client.\nhttps://svelte.dev/e/fn_unavailable_on_client`);
 
 		error.name = 'Svelte error';
 
 		throw error;
 	} else {
-		throw new Error(`https://svelte.dev/e/flush_sync_in_effect`);
+		throw new Error(`https://svelte.dev/e/fn_unavailable_on_client`);
 	}
 }
 

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

@@ -0,0 +1,97 @@
+/** @import { Decode, Hydratable, Transport } from '#shared' */
+import { async_mode_flag } from '../flags/index.js';
+import { hydrating } from './dom/hydration.js';
+import * as w from './warnings.js';
+import * as e from './errors.js';
+
+/**
+ * @template T
+ * @param {string} key
+ * @param {() => T} fn
+ * @param {Transport<T>} [options]
+ * @returns {T}
+ */
+function isomorphic_hydratable(key, fn, options) {
+	if (!async_mode_flag) {
+		e.experimental_async_required('hydratable');
+	}
+
+	return access_hydratable_store(
+		key,
+		(val, has) => {
+			if (!has) {
+				w.hydratable_missing_but_expected(key);
+				return fn();
+			}
+			return decode(val, options?.decode);
+		},
+		fn
+	);
+}
+
+isomorphic_hydratable['get'] = get_hydratable_value;
+isomorphic_hydratable['has'] = has_hydratable_value;
+isomorphic_hydratable['set'] = () => e.fn_unavailable_on_client('hydratable.set');
+
+/** @type {Hydratable} */
+const hydratable = isomorphic_hydratable;
+
+export { hydratable };
+
+/**
+ * @template T
+ * @param {string} key
+ * @param {{ decode?: Decode<T> }} [options]
+ * @returns {T | undefined}
+ */
+function get_hydratable_value(key, options = {}) {
+	if (!async_mode_flag) {
+		e.experimental_async_required('hydratable.get');
+	}
+
+	return access_hydratable_store(
+		key,
+		(val) => decode(val, options.decode),
+		() => undefined
+	);
+}
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function has_hydratable_value(key) {
+	if (!async_mode_flag) {
+		e.experimental_async_required('hydratable.set');
+	}
+	return access_hydratable_store(
+		key,
+		(_, has) => has,
+		() => false
+	);
+}
+
+/**
+ * @template T
+ * @param {string} key
+ * @param {(val: unknown, has: boolean) => T} on_hydrating
+ * @param {() => T} on_not_hydrating
+ * @returns {T}
+ */
+function access_hydratable_store(key, on_hydrating, on_not_hydrating) {
+	if (!hydrating) {
+		return on_not_hydrating();
+	}
+	var store = window.__svelte?.h;
+	return on_hydrating(store?.get(key), store?.has(key) ?? false);
+}
+
+/**
+ * @template T
+ * @param {unknown} val
+ * @param {Decode<T> | undefined} decode
+ * @returns {T}
+ */
+function decode(val, decode) {
+	return (decode ?? ((val) => /** @type {T} */ (val)))(val);
+}

packages/svelte/src/internal/client/reactivity/batch.js

@@ -895,7 +895,7 @@ export function eager(fn) {
  */
 export function fork(fn) {
 	if (!async_mode_flag) {
-		e.experimental_async_fork();
+		e.experimental_async_required('fork');
 	}
 
 	if (current_batch !== null) {