feat(PersistedState): compile-time guard preveting undefined as a valid value in the stored type

`undefined` already used internally by `PersistedState` as a special case to indicate that the value is not present in storage, and in case of deserialisation failure.

This make using `undefined` in user-code a footgun, because for example `persistentState.current = undefined` is not working as expected, being a NOOP instead of emptying the state.

While this is technically a breaking-change, I consider it a patch because the user-code impacted is buggy anyway.

Alternatively another approach would be allow undefined state. A draft PR is available here: svecosystem#408. I did not get to the end of it, because the issue is that undefined has no valid JSON value, so it would require additional (de)serialisation logic, especially for custom ones.

Author: kraktus

.changeset/pretty-ends-sing.md

@@ -0,0 +1,5 @@
+---
+"runed": patch
+---
+
+: PersistedState: compile-time guard to prevent `undefined` as a valid value in the stored type

packages/runed/src/lib/utilities/persisted-state/persisted-state.svelte.ts

@@ -2,9 +2,11 @@ import { defaultWindow, type ConfigurableWindow } from "$lib/internal/configurab
 import { on } from "svelte/events";
 import { createSubscriber } from "svelte/reactivity";
 
+type NoUndefined<T> = undefined extends T ? never : T;
+
 type Serializer<T> = {
 	serialize: (value: T) => string;
-	deserialize: (value: string) => T | undefined;
+	deserialize: (value: string) => NoUndefined<T> | undefined;
 };
 
 type StorageType = "local" | "session";
@@ -55,18 +57,18 @@ type PersistedStateOptions<T> = {
 
 function proxy<T>(
 	value: unknown,
-	root: T | undefined,
+	root: NoUndefined<T> | undefined,
 	proxies: WeakMap<WeakKey, unknown>,
 	subscribe: VoidFunction | undefined,
 	update: VoidFunction | undefined,
-	serialize: (root?: T | undefined) => void
-): T {
+	serialize: (root?: NoUndefined<T> | undefined) => void
+): NoUndefined<T> {
 	if (value === null || typeof value !== "object") {
-		return value as T;
+		return value as NoUndefined<T>;
 	}
 	const proto = Object.getPrototypeOf(value);
 	if (proto !== null && proto !== Object.prototype && !Array.isArray(value)) {
-		return value as T;
+		return value as NoUndefined<T>;
 	}
 	let p = proxies.get(value);
 	if (!p) {
@@ -84,19 +86,21 @@ function proxy<T>(
 		});
 		proxies.set(value, p);
 	}
-	return p as T;
+	return p as NoUndefined<T>;
 }
 
 /**
  * Creates reactive state that is persisted and synchronized across browser sessions and tabs using Web Storage.
+ * The stored type must not include `undefined` as a valid value, if you with to have a empty value, use `null` instead.
+ * 
  * @param key The unique key used to store the state in the storage.
  * @param initialValue The initial value of the state if not already present in the storage.
  * @param options Configuration options including storage type, serializer for complex data types, and whether to sync state changes across tabs.
  *
  * @see {@link https://runed.dev/docs/utilities/persisted-state}
  */
 export class PersistedState<T> {
-	#current: T | undefined;
+	#current: NoUndefined<T> | undefined;
 	#key: string;
 	#serializer: Serializer<T>;
 	#storage?: Storage;
@@ -109,7 +113,7 @@ export class PersistedState<T> {
 	#syncTabs: boolean;
 	#storageType: StorageType;
 
-	constructor(key: string, initialValue: T, options: PersistedStateOptions<T> = {}) {
+	constructor(key: string, initialValue: NoUndefined<T>, options: PersistedStateOptions<T> = {}) {
 		const {
 			storage: storageType = "local",
 			serializer = { serialize: JSON.stringify, deserialize: JSON.parse },
@@ -141,10 +145,10 @@ export class PersistedState<T> {
 		this.#setupStorageListener();
 	}
 
-	get current(): T {
+	get current(): NoUndefined<T> {
 		this.#subscribe?.();
 
-		let root: T | undefined;
+		let root: NoUndefined<T> | undefined;
 		if (this.#connected) {
 			// when we're connected to storage, we use storage as the source of truth
 			const storageItem = this.#storage?.getItem(this.#key);
@@ -163,7 +167,7 @@ export class PersistedState<T> {
 		);
 	}
 
-	set current(newValue: T) {
+	set current(newValue: NoUndefined<T>) {
 		this.#serialize(newValue);
 		this.#update?.();
 	}
@@ -174,7 +178,7 @@ export class PersistedState<T> {
 		this.#update?.();
 	};
 
-	#deserialize(value: string): T | undefined {
+	#deserialize(value: string): NoUndefined<T> | undefined {
 		try {
 			return this.#serializer.deserialize(value);
 		} catch (error) {
@@ -183,7 +187,7 @@ export class PersistedState<T> {
 		}
 	}
 
-	#serialize(value: T | undefined): void {
+	#serialize(value: NoUndefined<T> | undefined): void {
 		if (!this.#connected) {
 			// when we're not connected to storage, we only update the value in memory
 			this.#current = value;

packages/runed/src/lib/utilities/persisted-state/persisted-state.test.svelte.ts

@@ -383,7 +383,7 @@ describe("PersistedState", async () => {
 		});
 
 		testWithEffect("can set undefined then set a new value", () => {
-			const persistedState = new PersistedState<string | null>(key, initialValue);
+			const persistedState = new PersistedState<string | undefined>(key, initialValue);
 			persistedState.current = undefined;
 			expect(persistedState.current).toBe(undefined);