useLocalStorage

1"use client"
2 
3import * as React from "react"
4 
5/**
6 * Custom event name used to sync instances inside one tab. The native "storage" event
7 * only fires in *other* tabs/windows — the document that performed the write never
8 * hears its own storage event — so multiple `useLocalStorage(key)` instances in one
9 * tab notify each other through this custom event.
10 */
11const SYNC_EVENT = "zyeon:local-storage-sync"
12 
13interface SyncEventDetail {
14  key: string
15}
16 
17function readRawValue(key: string): string | null {
18  try {
19    return window.localStorage.getItem(key)
20  } catch {
21    // in private mode, or with storage disabled outright, touching localStorage can itself throw
22    return null
23  }
24}
25 
26function parseOrFallback<T>(raw: string | null, fallback: T): T {
27  if (raw === null) return fallback
28  try {
29    return JSON.parse(raw) as T
30  } catch {
31    // hand-edited or corrupted storage: fall back to the default, never throw
32    return fallback
33  }
34}
35 
36/**
37 * Per-key cache of "the raw string last read + what it parsed to".
38 *
39 * This is the load-bearing piece of the hook: `useSyncExternalStore` requires that,
40 * while the store has not changed, two calls to `getSnapshot` return the `===` same
41 * reference. `JSON.parse` allocates a fresh object/array every time, so re-parsing on
42 * every `getSnapshot` makes React believe the store changed on every render and
43 * re-render forever. Caching the raw string together with its parsed result means we
44 * re-parse only when the raw string actually changed, and return the same reference
45 * otherwise.
46 */
47const snapshotCache = new Map<string, { raw: string | null; value: unknown }>()
48 
49function getSnapshotFor<T>(key: string, fallback: T): T {
50  const raw = readRawValue(key)
51  // key absent: return this instance's own initialValue (held in a per-instance ref,
52  // so the reference is stable) and do not write the shared cache — otherwise, with two
53  // instances on the same key but different defaults, the one mounted later reads the
54  // earlier one's cached default.
55  if (raw === null) return fallback
56  const cached = snapshotCache.get(key)
57  if (cached && cached.raw === raw) {
58    return cached.value as T
59  }
60  const value = parseOrFallback(raw, fallback)
61  snapshotCache.set(key, { raw, value })
62  return value
63}
64 
65function dispatchSync(key: string) {
66  window.dispatchEvent(new CustomEvent<SyncEventDetail>(SYNC_EVENT, { detail: { key } }))
67}
68 
69/**
70 * State backed by localStorage, with the same call signature as `useState`:
71// … truncated