Function usePersistedState

src/browser/hooks/usePersistedState.ts:225–329

(
  key: string,
  initialValue: T,
  options?: UsePersistedStateOptions
)

 * @returns [state, setState] tuple matching useState API
 */
export function usePersistedState<T>(
  key: string,
  initialValue: T,
  options?: UsePersistedStateOptions
): [T, Dispatch<SetStateAction<T>>] {
  // Unique component ID for distinguishing self-updates.
  const componentIdRef = useRef(Math.random().toString(36));

  ensureStorageListenerInstalled();

  const subscribe = useCallback(
    (callback: () => void) => {
      return addSubscriber(key, {
        callback,
        componentId: componentIdRef.current,
        listener: Boolean(options?.listener),
      });
    },
    [key, options?.listener]
  );

  // Match the previous `usePersistedState` behavior: `initialValue` is only used
  // as the default when no value is stored; changes to `initialValue` should not
  // reinitialize state.
  const initialValueRef = useRef(initialValue);

  // useSyncExternalStore requires getSnapshot() to be referentially stable when
  // the underlying store value is unchanged. Since localStorage values are JSON,
  // we cache the parsed value by raw string.
  const snapshotRef = useRef<{ key: string; raw: string | null; value: T } | null>(null);

  const getSnapshot = useCallback((): T => {
    if (typeof window === "undefined" || !window.localStorage) {
      return initialValueRef.current;
    }

    try {
      const raw = window.localStorage.getItem(key);

      if (raw === null || raw === "undefined") {
        if (snapshotRef.current?.key === key && snapshotRef.current.raw === null) {
          return snapshotRef.current.value;
        }

        snapshotRef.current = {
          key,
          raw: null,
          value: initialValueRef.current,
        };

        return initialValueRef.current;
      }

      if (snapshotRef.current?.key === key && snapshotRef.current.raw === raw) {
        return snapshotRef.current.value;
      }

      const parsed = JSON.parse(raw) as T;