@c9up/aurora 0.1.21 → 0.1.22

package/dist/browser.d.ts

@@ -31,10 +31,14 @@ export interface WebStorageOptions {
     area?: StorageArea;
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -45,13 +49,31 @@ export declare class WebStorage {
     constructor(options?: WebStorageOptions);
     /** The on-disk key for `key`, namespaced by the configured prefix. */
     fullKey(key: string): string;
-    get<T>(key: string): T | null;
-    set(key: string, value: unknown): void;
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
+    get(key: string): string | null;
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
+    set(key: string, value: string): void;
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON<T>(key: string): T | null;
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key: string, value: unknown): void;
     /** Whether `key` is present (and not the server). */
     has(key: string): boolean;
     remove(key: string): void;
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-    getOrSet<T>(key: string, factory: () => T): T;
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+    getOrSet(key: string, factory: () => string): string;
     /** Keys in this store, prefix stripped. Empty array during SSR. */
     keys(): string[];
     /** Remove this store's keys. With no prefix this clears the whole area. */

package/dist/browser.js

@@ -29,10 +29,14 @@ export function reload() {
     }
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -56,31 +60,53 @@ export class WebStorage {
     fullKey(key) {
         return this.#prefix + key;
     }
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
     get(key) {
         const backend = this.#backend();
         if (!backend)
             return null;
-        const raw = backend.getItem(this.fullKey(key));
-        if (raw === null)
-            return null;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
+        return backend.getItem(this.fullKey(key));
     }
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
     set(key, value) {
         const backend = this.#backend();
         if (!backend)
             return;
         try {
-            backend.setItem(this.fullKey(key), JSON.stringify(value));
+            backend.setItem(this.fullKey(key), value);
         }
         catch {
             // QuotaExceededError / Safari private mode — best-effort write.
         }
     }
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON(key) {
+        const raw = this.get(key);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key, value) {
+        this.set(key, JSON.stringify(value));
+    }
     /** Whether `key` is present (and not the server). */
     has(key) {
         const backend = this.#backend();
@@ -91,7 +117,7 @@ export class WebStorage {
     remove(key) {
         this.#backend()?.removeItem(this.fullKey(key));
     }
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
     getOrSet(key, factory) {
         const existing = this.get(key);
         if (existing !== null)
@@ -148,11 +174,12 @@ export const session = new WebStorage({ area: "session" });
  */
 export function persistedSignal(key, initial, options = {}) {
     const store = new WebStorage(options);
-    const stored = store.get(key);
+    const stored = store.getJSON(key);
     const sig = signal(stored !== null ? stored : initial);
     // Mirror every change back to storage; runs once immediately, then on change.
+    // JSON so any T (object, number, boolean, string) round-trips.
     effect(() => {
-        store.set(key, sig());
+        store.setJSON(key, sig());
     });
     if ((options.crossTab ?? true) &&
         (options.area ?? "local") === "local" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",

package/src/browser.ts

@@ -50,10 +50,14 @@ export interface WebStorageOptions {
 }
 
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -80,28 +84,52 @@ export class WebStorage {
 		return this.#prefix + key;
 	}
 
-	get<T>(key: string): T | null {
+	/**
+	 * Read the raw string at `key` — a thin, SSR-safe pass-through over
+	 * `localStorage.getItem` (returns `null` on the server or a missing key).
+	 * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+	 * structured values.
+	 */
+	get(key: string): string | null {
 		const backend = this.#backend();
 		if (!backend) return null;
-		const raw = backend.getItem(this.fullKey(key));
-		if (raw === null) return null;
-		try {
-			return JSON.parse(raw) as T;
-		} catch {
-			return null;
-		}
+		return backend.getItem(this.fullKey(key));
 	}
 
-	set(key: string, value: unknown): void {
+	/**
+	 * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+	 * errors are swallowed — best-effort). No encoding, like
+	 * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+	 */
+	set(key: string, value: string): void {
 		const backend = this.#backend();
 		if (!backend) return;
 		try {
-			backend.setItem(this.fullKey(key), JSON.stringify(value));
+			backend.setItem(this.fullKey(key), value);
 		} catch {
 			// QuotaExceededError / Safari private mode — best-effort write.
 		}
 	}
 
+	/**
+	 * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+	 * missing key, or malformed JSON. Pair with {@link setJSON}.
+	 */
+	getJSON<T>(key: string): T | null {
+		const raw = this.get(key);
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+	setJSON(key: string, value: unknown): void {
+		this.set(key, JSON.stringify(value));
+	}
+
 	/** Whether `key` is present (and not the server). */
 	has(key: string): boolean {
 		const backend = this.#backend();
@@ -113,9 +141,9 @@ export class WebStorage {
 		this.#backend()?.removeItem(this.fullKey(key));
 	}
 
-	/** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-	getOrSet<T>(key: string, factory: () => T): T {
-		const existing = this.get<T>(key);
+	/** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+	getOrSet(key: string, factory: () => string): string {
+		const existing = this.get(key);
 		if (existing !== null) return existing;
 		const value = factory();
 		this.set(key, value);
@@ -183,12 +211,13 @@ export function persistedSignal<T>(
 	options: PersistedSignalOptions = {},
 ): Signal<T> {
 	const store = new WebStorage(options);
-	const stored = store.get<T>(key);
+	const stored = store.getJSON<T>(key);
 	const sig = signal<T>(stored !== null ? stored : initial);
 
 	// Mirror every change back to storage; runs once immediately, then on change.
+	// JSON so any T (object, number, boolean, string) round-trips.
 	effect(() => {
-		store.set(key, sig());
+		store.setJSON(key, sig());
 	});
 
 	if (