From dfb675551413e9ac8bcaedebf736a73cecb94116 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Mon, 12 Aug 2024 15:42:33 -0400
Subject: [PATCH] feat: add compiler error when encountering a $-prefixed store
 value outside a `.svelte` file (#12799)

* feat: add compiler error when encountering a $-prefixed store value outside a .svelte file

* add fromState/toState APIs

* another test, update types

* rename fromState to toStore, and toState to fromStore

* docs

* add docs

* separate client/server entry points for svelte/store
---
 .changeset/curvy-papayas-pretend.md           |   5 +
 .../svelte/messages/compile-errors/script.md  |   6 +
 packages/svelte/package.json                  |   3 +-
 packages/svelte/src/compiler/errors.js        |   9 +
 .../src/compiler/phases/2-analyze/index.js    |   6 +
 packages/svelte/src/motion/spring.js          |   2 +-
 packages/svelte/src/motion/tweened.js         |   2 +-
 packages/svelte/src/store/index-client.js     | 165 ++++++++++++++++++
 packages/svelte/src/store/index-server.js     | 101 +++++++++++
 packages/svelte/src/store/public.d.ts         |   2 +-
 .../svelte/src/store/{ => shared}/index.js    |  10 +-
 .../_config.js                                |   8 +
 .../main.svelte.js                            |   3 +
 packages/svelte/tests/store/test.ts           | 108 +++++++++++-
 packages/svelte/types/index.d.ts              |  11 ++
 .../routes/docs/content/01-api/05-imports.md  |  41 +++++
 16 files changed, 472 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/curvy-papayas-pretend.md
 create mode 100644 packages/svelte/src/store/index-client.js
 create mode 100644 packages/svelte/src/store/index-server.js
 rename packages/svelte/src/store/{ => shared}/index.js (95%)
 create mode 100644 packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/_config.js
 create mode 100644 packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/main.svelte.js

diff --git a/.changeset/curvy-papayas-pretend.md b/.changeset/curvy-papayas-pretend.md
new file mode 100644
index 0000000000..d5357dc5bc
--- /dev/null
+++ b/.changeset/curvy-papayas-pretend.md
@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: add compiler error when encountering a $-prefixed store value outside a .svelte file
diff --git a/packages/svelte/messages/compile-errors/script.md b/packages/svelte/messages/compile-errors/script.md
index d31c04b99c..6e15fa06d5 100644
--- a/packages/svelte/messages/compile-errors/script.md
+++ b/packages/svelte/messages/compile-errors/script.md
@@ -149,3 +149,9 @@
 ## store_invalid_subscription
 
 > Cannot reference store value inside `<script context="module">`
+
+## store_invalid_subscription_module
+
+> Cannot reference store value outside a `.svelte` file
+
+Using a `$` prefix to refer to the value of a store is only possible inside `.svelte` files, where Svelte can automatically create subscriptions when a component is mounted and unsubscribe when the component is unmounted. Consider migrating to runes instead.
diff --git a/packages/svelte/package.json b/packages/svelte/package.json
index 98bf7a1fa5..57d8fa2f3d 100644
--- a/packages/svelte/package.json
+++ b/packages/svelte/package.json
@@ -76,7 +76,8 @@
     },
     "./store": {
       "types": "./types/index.d.ts",
-      "default": "./src/store/index.js"
+      "browser": "./src/store/index-client.js",
+      "default": "./src/store/index-server.js"
     },
     "./transition": {
       "types": "./types/index.d.ts",
diff --git a/packages/svelte/src/compiler/errors.js b/packages/svelte/src/compiler/errors.js
index 8b650ebf3c..3892e688e4 100644
--- a/packages/svelte/src/compiler/errors.js
+++ b/packages/svelte/src/compiler/errors.js
@@ -415,6 +415,15 @@ export function store_invalid_subscription(node) {
 	e(node, "store_invalid_subscription", "Cannot reference store value inside `<script context=\"module\">`");
 }
 
+/**
+ * Cannot reference store value outside a `.svelte` file
+ * @param {null | number | NodeLike} node
+ * @returns {never}
+ */
+export function store_invalid_subscription_module(node) {
+	e(node, "store_invalid_subscription_module", "Cannot reference store value outside a `.svelte` file");
+}
+
 /**
  * Declaration cannot be empty
  * @param {null | number | NodeLike} node
diff --git a/packages/svelte/src/compiler/phases/2-analyze/index.js b/packages/svelte/src/compiler/phases/2-analyze/index.js
index 40e8719a40..199ca5c1af 100644
--- a/packages/svelte/src/compiler/phases/2-analyze/index.js
+++ b/packages/svelte/src/compiler/phases/2-analyze/index.js
@@ -219,6 +219,12 @@ export function analyze_module(ast, options) {
 		if (name === '$' || name[1] === '$') {
 			e.global_reference_invalid(references[0].node, name);
 		}
+
+		const binding = scope.get(name.slice(1));
+
+		if (binding !== null) {
+			e.store_invalid_subscription_module(references[0].node);
+		}
 	}
 
 	walk(
diff --git a/packages/svelte/src/motion/spring.js b/packages/svelte/src/motion/spring.js
index c3b4177579..c21ef42f99 100644
--- a/packages/svelte/src/motion/spring.js
+++ b/packages/svelte/src/motion/spring.js
@@ -1,7 +1,7 @@
 /** @import { Task } from '#client' */
 /** @import { SpringOpts, SpringUpdateOpts, TickContext } from './private.js' */
 /** @import { Spring } from './public.js' */
-import { writable } from '../store/index.js';
+import { writable } from '../store/shared/index.js';
 import { loop } from '../internal/client/loop.js';
 import { raf } from '../internal/client/timing.js';
 import { is_date } from './utils.js';
diff --git a/packages/svelte/src/motion/tweened.js b/packages/svelte/src/motion/tweened.js
index a1ec502fc8..a264cc9da5 100644
--- a/packages/svelte/src/motion/tweened.js
+++ b/packages/svelte/src/motion/tweened.js
@@ -1,7 +1,7 @@
 /** @import { Task } from '../internal/client/types' */
 /** @import { Tweened } from './public' */
 /** @import { TweenedOptions } from './private' */
-import { writable } from '../store/index.js';
+import { writable } from '../store/shared/index.js';
 import { raf } from '../internal/client/timing.js';
 import { loop } from '../internal/client/loop.js';
 import { linear } from '../easing/index.js';
diff --git a/packages/svelte/src/store/index-client.js b/packages/svelte/src/store/index-client.js
new file mode 100644
index 0000000000..b612124e3c
--- /dev/null
+++ b/packages/svelte/src/store/index-client.js
@@ -0,0 +1,165 @@
+/** @import { Readable, Writable } from './public.js' */
+import { noop } from '../internal/shared/utils.js';
+import {
+	effect_root,
+	effect_tracking,
+	render_effect
+} from '../internal/client/reactivity/effects.js';
+import { source } from '../internal/client/reactivity/sources.js';
+import { get as get_source, tick } from '../internal/client/runtime.js';
+import { increment } from '../reactivity/utils.js';
+import { get, writable } from './shared/index.js';
+
+export { derived, get, readable, readonly, writable } from './shared/index.js';
+
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @param {(v: V) => void} set
+ * @returns {Writable<V>}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @returns {Readable<V>}
+ */
+/**
+ * Create a store from a function that returns state, and (to make a writable store), an
+ * optional second function that sets state.
+ *
+ * ```ts
+ * import { toStore } from 'svelte/store';
+ *
+ * let count = $state(0);
+ *
+ * const store = toStore(() => count, (v) => (count = v));
+ * ```
+ * @template V
+ * @param {() => V} get
+ * @param {(v: V) => void} [set]
+ * @returns {Writable<V> | Readable<V>}
+ */
+export function toStore(get, set) {
+	const store = writable(get(), (set) => {
+		let ran = false;
+
+		// TODO do we need a different implementation on the server?
+		const teardown = effect_root(() => {
+			render_effect(() => {
+				const value = get();
+				if (ran) set(value);
+			});
+		});
+
+		ran = true;
+
+		return teardown;
+	});
+
+	if (set) {
+		return {
+			set,
+			update: (fn) => set(fn(get())),
+			subscribe: store.subscribe
+		};
+	}
+
+	return {
+		subscribe: store.subscribe
+	};
+}
+
+/**
+ * @template V
+ * @overload
+ * @param {Writable<V>} store
+ * @returns {{ current: V }}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {Readable<V>} store
+ * @returns {{ readonly current: V }}
+ */
+/**
+ * Convert a store to an object with a reactive `current` property. If `store`
+ * is a readable store, `current` will be a readonly property.
+ *
+ * ```ts
+ * import { fromStore, get, writable } from 'svelte/store';
+ *
+ * const store = writable(0);
+ *
+ * const count = fromStore(store);
+ *
+ * count.current; // 0;
+ * store.set(1);
+ * count.current; // 1
+ *
+ * count.current += 1;
+ * get(store); // 2
+ * ```
+ * @template V
+ * @param {Writable<V> | Readable<V>} store
+ */
+export function fromStore(store) {
+	let value = /** @type {V} */ (undefined);
+	let version = source(0);
+	let subscribers = 0;
+
+	let unsubscribe = noop;
+
+	function current() {
+		if (effect_tracking()) {
+			get_source(version);
+
+			render_effect(() => {
+				if (subscribers === 0) {
+					let ran = false;
+
+					unsubscribe = store.subscribe((v) => {
+						value = v;
+						if (ran) increment(version);
+					});
+
+					ran = true;
+				}
+
+				subscribers += 1;
+
+				return () => {
+					subscribers -= 1;
+
+					tick().then(() => {
+						if (subscribers === 0) {
+							unsubscribe();
+						}
+					});
+				};
+			});
+
+			return value;
+		}
+
+		return get(store);
+	}
+
+	if ('set' in store) {
+		return {
+			get current() {
+				return current();
+			},
+			set current(v) {
+				store.set(v);
+			}
+		};
+	}
+
+	return {
+		get current() {
+			return current();
+		}
+	};
+}
diff --git a/packages/svelte/src/store/index-server.js b/packages/svelte/src/store/index-server.js
new file mode 100644
index 0000000000..3eddd781f2
--- /dev/null
+++ b/packages/svelte/src/store/index-server.js
@@ -0,0 +1,101 @@
+/** @import { Readable, Writable } from './public.js' */
+import { get, writable } from './shared/index.js';
+
+export { derived, get, readable, readonly, writable } from './shared/index.js';
+
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @param {(v: V) => void} set
+ * @returns {Writable<V>}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {() => V} get
+ * @returns {Readable<V>}
+ */
+/**
+ * Create a store from a function that returns state, and (to make a writable store), an
+ * optional second function that sets state.
+ *
+ * ```ts
+ * import { toStore } from 'svelte/store';
+ *
+ * let count = $state(0);
+ *
+ * const store = toStore(() => count, (v) => (count = v));
+ * ```
+ * @template V
+ * @param {() => V} get
+ * @param {(v: V) => void} [set]
+ * @returns {Writable<V> | Readable<V>}
+ */
+export function toStore(get, set) {
+	const store = writable(get());
+
+	if (set) {
+		return {
+			set,
+			update: (fn) => set(fn(get())),
+			subscribe: store.subscribe
+		};
+	}
+
+	return {
+		subscribe: store.subscribe
+	};
+}
+
+/**
+ * @template V
+ * @overload
+ * @param {Writable<V>} store
+ * @returns {{ current: V }}
+ */
+/**
+ * @template V
+ * @overload
+ * @param {Readable<V>} store
+ * @returns {{ readonly current: V }}
+ */
+/**
+ * Convert a store to an object with a reactive `current` property. If `store`
+ * is a readable store, `current` will be a readonly property.
+ *
+ * ```ts
+ * import { fromStore, get, writable } from 'svelte/store';
+ *
+ * const store = writable(0);
+ *
+ * const count = fromStore(store);
+ *
+ * count.current; // 0;
+ * store.set(1);
+ * count.current; // 1
+ *
+ * count.current += 1;
+ * get(store); // 2
+ * ```
+ * @template V
+ * @param {Writable<V> | Readable<V>} store
+ */
+export function fromStore(store) {
+	if ('set' in store) {
+		return {
+			get current() {
+				return get(store);
+			},
+			set current(v) {
+				store.set(v);
+			}
+		};
+	}
+
+	return {
+		get current() {
+			return get(store);
+		}
+	};
+}
diff --git a/packages/svelte/src/store/public.d.ts b/packages/svelte/src/store/public.d.ts
index 63cb6bfc4c..ec262f7ebf 100644
--- a/packages/svelte/src/store/public.d.ts
+++ b/packages/svelte/src/store/public.d.ts
@@ -48,4 +48,4 @@ interface Writable<T> extends Readable<T> {
 
 export { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable };
 
-export * from './index.js';
+export * from './index-client.js';
diff --git a/packages/svelte/src/store/index.js b/packages/svelte/src/store/shared/index.js
similarity index 95%
rename from packages/svelte/src/store/index.js
rename to packages/svelte/src/store/shared/index.js
index 393144cff0..9bf08b4160 100644
--- a/packages/svelte/src/store/index.js
+++ b/packages/svelte/src/store/shared/index.js
@@ -1,8 +1,8 @@
-/** @import { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable } from './public' */
-/** @import { Stores, StoresValues, SubscribeInvalidateTuple } from './private' */
-import { noop, run_all } from '../internal/shared/utils.js';
-import { safe_not_equal } from '../internal/client/reactivity/equality.js';
-import { subscribe_to_store } from './utils.js';
+/** @import { Readable, StartStopNotifier, Subscriber, Unsubscriber, Updater, Writable } from '../public.js' */
+/** @import { Stores, StoresValues, SubscribeInvalidateTuple } from '../private.js' */
+import { noop, run_all } from '../../internal/shared/utils.js';
+import { safe_not_equal } from '../../internal/client/reactivity/equality.js';
+import { subscribe_to_store } from '../utils.js';
 
 /**
  * @type {Array<SubscribeInvalidateTuple<any> | any>}
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/_config.js b/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/_config.js
new file mode 100644
index 0000000000..47ecd8f902
--- /dev/null
+++ b/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/_config.js
@@ -0,0 +1,8 @@
+import { test } from '../../test';
+
+export default test({
+	error: {
+		code: 'store_invalid_subscription_module',
+		message: 'Cannot reference store value outside a `.svelte` file'
+	}
+});
diff --git a/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/main.svelte.js b/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/main.svelte.js
new file mode 100644
index 0000000000..f4145e93ba
--- /dev/null
+++ b/packages/svelte/tests/compiler-errors/samples/runes-module-store-subscription/main.svelte.js
@@ -0,0 +1,3 @@
+import { store } from 'somewhere';
+
+console.log($store);
diff --git a/packages/svelte/tests/store/test.ts b/packages/svelte/tests/store/test.ts
index 6a89e39df8..74ad892577 100644
--- a/packages/svelte/tests/store/test.ts
+++ b/packages/svelte/tests/store/test.ts
@@ -1,5 +1,17 @@
 import { describe, it, assert } from 'vitest';
-import { readable, writable, derived, get, readonly, type Readable } from 'svelte/store';
+import {
+	readable,
+	writable,
+	derived,
+	get,
+	readonly,
+	toStore,
+	type Readable,
+	fromStore
+} from 'svelte/store';
+import { source, set } from '../../src/internal/client/reactivity/sources';
+import * as $ from '../../src/internal/client/runtime';
+import { effect_root, render_effect } from 'svelte/internal/client';
 
 describe('writable', () => {
 	it('creates a writable store', () => {
@@ -574,3 +586,97 @@ describe('readonly', () => {
 		assert.throws(() => readableStore.set(3));
 	});
 });
+
+describe('toStore', () => {
+	it('creates a readable store from state', () => {
+		const count = source(0);
+
+		const store = toStore(() => $.get(count));
+
+		const log: number[] = [];
+
+		const unsubscribe = store.subscribe((value) => {
+			log.push(value);
+		});
+
+		assert.deepEqual(log, [0]);
+
+		set(count, 1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		unsubscribe();
+	});
+
+	it('creates a writable store from state', () => {
+		const count = source(0);
+
+		const store = toStore(
+			() => $.get(count),
+			(v) => set(count, v)
+		);
+
+		const log: number[] = [];
+
+		const unsubscribe = store.subscribe((value) => {
+			log.push(value);
+		});
+
+		assert.deepEqual(log, [0]);
+
+		set(count, 1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		store.set(2);
+		assert.equal($.get(count), 2);
+
+		unsubscribe();
+	});
+});
+
+describe('fromStore', () => {
+	it('creates state from a writable store', () => {
+		const store = writable(0);
+
+		const count = fromStore(store);
+
+		assert.equal(count.current, 0);
+
+		const log: number[] = [];
+
+		const teardown = effect_root(() => {
+			render_effect(() => {
+				log.push(count.current);
+			});
+		});
+
+		assert.deepEqual(log, [0]);
+
+		store.set(1);
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1]);
+
+		count.current = 2;
+		$.flush_sync();
+		assert.deepEqual(log, [0, 1, 2]);
+
+		assert.equal(get(store), 2);
+
+		teardown();
+	});
+
+	it('creates state from a readable store', () => {
+		const store = readable(0);
+
+		const count = fromStore(store);
+
+		assert.equal(count.current, 0);
+
+		assert.throws(
+			// @ts-expect-error property is readonly
+			() => (count.current += 1),
+			'Cannot set property current of #<Object> which has only a getter'
+		);
+	});
+});
diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts
index f31cb2a6d3..9b6198c547 100644
--- a/packages/svelte/types/index.d.ts
+++ b/packages/svelte/types/index.d.ts
@@ -2306,6 +2306,17 @@ declare module 'svelte/store' {
 		 */
 		update(this: void, updater: Updater<T>): void;
 	}
+	export function toStore<V>(get: () => V, set: (v: V) => void): Writable<V>;
+
+	export function toStore<V>(get: () => V): Readable<V>;
+
+	export function fromStore<V>(store: Writable<V>): {
+		current: V;
+	};
+
+	export function fromStore<V>(store: Readable<V>): {
+		readonly current: V;
+	};
 	/**
 	 * Creates a `Readable` store that allows reading by subscription.
 	 *
diff --git a/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md b/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
index a42cde2319..7cbec56e17 100644
--- a/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
+++ b/sites/svelte-5-preview/src/routes/docs/content/01-api/05-imports.md
@@ -192,6 +192,47 @@ const result = render(App, {
 
 If the `css` compiler option was set to `'injected'`, `<style>` elements will be included in the `head`.
 
+## `svelte/store`
+
+In addition to the existing store-related imports such as `writable`, `svelte/store` gains two new functions: `fromStore` and `toStore`. These allow you to easily use stores and rune-based state interchangeably, even outside `.svelte` files.
+
+### `fromStore`
+
+Takes a store and turns it into an object with a reactive (and readonly, if the store is not [writable](https://svelte.dev/docs/svelte-store#writable)) `current` property.
+
+```js
+import { fromStore, get, writable } from 'svelte/store';
+
+const store = writable(0);
+
+const count = fromStore(store);
+
+count.current; // 0;
+store.set(1);
+count.current; // 1
+
+count.current += 1;
+get(store); // 2
+```
+
+### `toStore`
+
+Creates a store from a function that returns reactive state (and, optionally, a second function that sets the state):
+
+```js
+import { toStore } from 'svelte/store';
+
+let count = $state(0);
+
+const store = toStore(
+	() => count,
+	(v) => (count = v)
+);
+
+store.set(1);
+count; // 1
+```
+
 ## `svelte/elements`
 
 Svelte provides built-in [DOM types](https://github.com/sveltejs/svelte/blob/master/packages/svelte/elements.d.ts). A common use case for DOM types is forwarding props to an HTML element. To properly type your props and get full intellisense, your props interface should extend the attributes type for your HTML element: