@plq/use-persisted-state 1.3.0 → 1.4.0

package/src/utils/create-web-storage.ts

@@ -1,63 +1,76 @@
-import { Storage, StorageChange, StorageChangeEvent, StorageChangeListener } from '../@types/storage'
+import type { Storage, StorageChange, StorageChangeEvent } from '../@types/storage'
+import { createChangeNotifier } from './change-notifier'
+import { addRoute, removeRoute, type StorageEventRoute } from './storage-event-router'
 
-const listeners = new Set<StorageChangeListener>()
-
-function fireStorageEvent(changes: { [key: string]: StorageChange }) {
-  listeners.forEach(listener => {
-    listener(changes)
-  })
+function toKeyList(keys: string | string[]): string[] {
+  return Array.isArray(keys) ? keys : [keys]
 }
 
-window.addEventListener('storage', event => {
-  if (event.key) {
-    const changes = {
-      [event.key]: {
-        newValue: event.newValue,
-        oldValue: event.oldValue,
-      },
+/**
+ * Adapts a Web Storage area to the library's `Storage` contract.
+ *
+ * Pass `undefined` where the global is missing, as it is on a server: the
+ * adapter then reads back nothing and **silently discards every write**, so a
+ * consumer keeps its initial value instead of the import throwing. Listeners
+ * are still accepted and reported, they simply never fire.
+ */
+export default (storage: globalThis.Storage | undefined): Storage => {
+  // Per-instance notifier: the localStorage and sessionStorage adapters must not
+  // share listeners, or a write to one area notifies subscribers of the other.
+  const notifier = createChangeNotifier()
+
+  // Only a missing global is inert. Anything else a caller passes has to fail
+  // on first use instead of swallowing their writes.
+  if (storage === undefined) {
+    return {
+      get: () => ({}),
+      set: () => {},
+      remove: () => {},
+      onChanged: notifier.onChanged,
     }
-
-    fireStorageEvent(changes)
   }
-})
-
-const onChanged: StorageChangeEvent = {
-  addListener(listener) {
-    listeners.add(listener)
-  },
-  removeListener(listener) {
-    listeners.delete(listener)
-  },
-  hasListener(listener) {
-    return listeners.has(listener)
-  },
-}
 
-export default (storage: globalThis.Storage): Storage => ({
-  get: keys => {
-    const result: { [key: string]: string } = {}
+  const route: StorageEventRoute = { storage, fire: notifier.fire }
+
+  // The DOM subscription is shared and reference counted: an adapter joins it
+  // with its first listener and lets go with its last, so factory calls nobody
+  // listens to leave nothing attached to the global object.
+  const onChanged: StorageChangeEvent = {
+    addListener(listener) {
+      notifier.onChanged.addListener(listener)
+
+      addRoute(route)
+    },
+    removeListener(listener) {
+      notifier.onChanged.removeListener(listener)
+
+      if (!notifier.hasListeners()) removeRoute(route)
+    },
+    hasListener(listener) {
+      return notifier.onChanged.hasListener(listener)
+    },
+  }
 
-    if (Array.isArray(keys)) {
-      keys.forEach(key => {
-        const item = typeof storage !== 'undefined' ? storage.getItem(key) : undefined
+  return {
+    get: keys => {
+      const result: { [key: string]: string } = {}
 
-        if (item) result[key] = item
-      })
-    } else {
-      const item = typeof storage !== 'undefined' ? storage.getItem(keys) : undefined
+      for (const key of toKeyList(keys)) {
+        const item = storage.getItem(key)
 
-      if (item) result[keys] = item
-    }
+        // `null` is the only answer that means absence: an empty string is a
+        // value the caller stored, and reporting it as a missing key loses it.
+        if (item !== null) result[key] = item
+      }
 
-    return result
-  },
-  set: items => {
-    const changes: { [key: string]: StorageChange } = {}
+      return result
+    },
+    set: items => {
+      const changes: { [key: string]: StorageChange } = {}
 
-    Object.entries(items).forEach(([key, value]) => {
-      const oldValue = typeof storage !== 'undefined' ? storage.getItem(key) : undefined
+      for (const [key, value] of Object.entries(items)) {
+        const oldValue = storage.getItem(key)
 
-      if (typeof storage !== 'undefined') {
         storage.setItem(key, value)
 
         changes[key] = {
@@ -65,41 +78,25 @@ export default (storage: globalThis.Storage): Storage => ({
           newValue: value,
         }
       }
-    })
-
-    if (Object.keys(changes).length > 0) fireStorageEvent(changes)
-  },
-  remove: keys => {
-    const changes: { [key: string]: StorageChange } = {}
 
-    if (Array.isArray(keys)) {
-      keys.forEach(key => {
-        const oldValue = typeof storage !== 'undefined' ? storage.getItem(key) : undefined
+      if (Object.keys(changes).length > 0) notifier.fire(changes)
+    },
+    remove: keys => {
+      const changes: { [key: string]: StorageChange } = {}
 
-        if (typeof storage !== 'undefined') {
-          storage.removeItem(key)
+      for (const key of toKeyList(keys)) {
+        const oldValue = storage.getItem(key)
 
-          changes[key] = {
-            oldValue,
-            newValue: null,
-          }
-        }
-      })
-    } else {
-      const oldValue = typeof storage !== 'undefined' ? storage.getItem(keys) : undefined
-
-      if (typeof storage !== 'undefined') {
-        storage.removeItem(keys)
+        storage.removeItem(key)
 
-        changes[keys] = {
+        changes[key] = {
           oldValue,
           newValue: null,
         }
       }
-    }
-
-    if (Object.keys(changes).length > 0) fireStorageEvent(changes)
-  },
-  onChanged,
-})
 
+      if (Object.keys(changes).length > 0) notifier.fire(changes)
+    },
+    onChanged,
+  }
+}

package/src/utils/extension-storage.ts

@@ -0,0 +1,79 @@
+import type { StorageChange, StorageChangeEvent } from '../@types/storage'
+import { type ChangeNotifier, createChangeNotifier } from './change-notifier'
+
+const TRACKED_AREAS = ['local', 'sync', 'managed'] as const
+
+export type Area = (typeof TRACKED_AREAS)[number]
+
+// Both browsers also report `session` changes, an area this library does not
+// expose. Dispatching one would read an undefined notifier and throw.
+function isTrackedArea(area: string): area is Area {
+  return (TRACKED_AREAS as readonly string[]).includes(area)
+}
+
+/**
+ * Extension storage holds arbitrary JSON, while this library only ever writes
+ * serialized strings. Anything else under a key belongs to other code and is
+ * reported as absent — which is what effectively happened before, once such a
+ * value reached `JSON.parse` and the hook fell back to its initial value.
+ */
+export function toStoredValue(value: unknown): string | null | undefined {
+  if (value === undefined) return
+
+  return typeof value === 'string' ? value : null
+}
+
+export function toStorageChanges(changes: { [key: string]: { oldValue?: unknown; newValue?: unknown } }): {
+  [key: string]: StorageChange
+} {
+  const result: { [key: string]: StorageChange } = {}
+
+  for (const [key, change] of Object.entries(changes)) {
+    result[key] = {
+      oldValue: toStoredValue(change.oldValue),
+      newValue: toStoredValue(change.newValue),
+    }
+  }
+
+  return result
+}
+
+export function toStoredItems(items: { [key: string]: unknown }): { [key: string]: string } {
+  const result: { [key: string]: string } = {}
+
+  for (const [key, value] of Object.entries(items)) {
+    if (typeof value === 'string') result[key] = value
+  }
+
+  return result
+}
+
+export interface ListenerRegistry {
+  fire(changes: { [key: string]: StorageChange }, area: string): void
+  createOnChanged(area: Area): StorageChangeEvent
+}
+
+/**
+ * Demultiplexes an extension's single `onChanged` event, which names the area
+ * that changed, to one notifier per area. Each adapter owns its own registry,
+ * so a change in one browser's storage never reaches listeners registered on
+ * another's.
+ */
+export function createListenerRegistry(): ListenerRegistry {
+  const notifiers: { [area in Area]: ChangeNotifier } = {
+    local: createChangeNotifier(),
+    sync: createChangeNotifier(),
+    managed: createChangeNotifier(),
+  }
+
+  return {
+    fire(changes, area) {
+      if (!isTrackedArea(area)) return
+
+      notifiers[area].fire(changes)
+    },
+    createOnChanged(area) {
+      return notifiers[area].onChanged
+    },
+  }
+}

package/src/utils/get-new-item.ts

@@ -1,4 +1,4 @@
-export default function<T>(key: string, persistedItem: string, newValue: T): string {
+export default function <T>(key: string, persistedItem: string, newValue: T): string {
   let persist: { [x: string]: unknown }
 
   try {

package/src/utils/get-new-value.ts

@@ -1,4 +1,4 @@
-import React from 'react'
+import type React from 'react'
 import { isFunction } from '@plq/is'
 
 export default function <T>(newState: React.SetStateAction<T>, state: T): T {

package/src/utils/get-persisted-value.ts

@@ -1,18 +1,33 @@
-import { isFunction } from '@plq/is'
+import { isFunction, isObject } from '@plq/is'
 
-export default function<T>(key:string, initialValue: T | (() => T), persist?: string): T {
-  let initialPersist: { [x: string]: unknown }
+/**
+ * Resolves the value a hook starts from: the persisted entry for `key` when the stored payload
+ * carries one, the initial value otherwise.
+ *
+ * Presence is decided by the key rather than by the value, so a persisted `null` comes back as
+ * the value the user set instead of being mistaken for an absence and replaced.
+ */
+export default function getPersistedValue<T>(key: string, initialValue: T | (() => T), persist?: string): T {
+  let initialPersist: unknown
 
   try {
     initialPersist = persist ? JSON.parse(persist) : {}
-  } catch {
+  } catch (err) {
+    // A shared backend can hold a foreign or truncated entry, so a parse failure is expected here
+    // and must not stop the component mounting. It is reported rather than swallowed because the
+    // fallback discards whatever was persisted, and because the change path logs the same failure.
+    console.error("use-persisted-state: Can't parse value from storage", err)
+
     initialPersist = {}
   }
 
-  let initialOrPersistedValue = isFunction(initialValue) ? initialValue()  : initialValue
+  let initialOrPersistedValue = isFunction(initialValue) ? initialValue() : initialValue
 
-  if (initialPersist && key in initialPersist) {
-    initialOrPersistedValue = (initialPersist[key] as T) ?? initialOrPersistedValue
+  // `JSON.parse` yields any JSON value, so a foreign entry can be a primitive,
+  // and `in` throws on one. This runs in the `useState` initializer, where a
+  // throw stops the component mounting instead of falling back.
+  if (isObject(initialPersist) && key in initialPersist) {
+    initialOrPersistedValue = initialPersist[key] as T
   }
 
   return initialOrPersistedValue

package/src/utils/is-async-storage.ts

@@ -1,30 +1,75 @@
-import {isFunction, isAsyncFunction, isPromise} from '@plq/is'
-import type {AsyncStorage} from '../@types/storage'
+import { isAsyncFunction, isFunction, isPromise } from '@plq/is'
+import type { AsyncStorage } from '../@types/storage'
 
+// An unvalidated candidate: its members are unknown until each one is checked.
+type StorageCandidate = {
+  get?: unknown
+  set?: unknown
+  remove?: unknown
+}
+
+// `AsyncStorage` is three methods, so every member has to be callable: a promise standing in for
+// one satisfies nothing the hook then does with it. `@plq/is` classifies async functions as their
+// own type, so `isFunction` rejects them and both checks are needed to admit a callable member.
+const isCallableMember = (member: unknown): boolean => isFunction(member) || isAsyncFunction(member)
+
+/**
+ * Narrows a storage to {@link AsyncStorage}, deciding which hook the entry point builds.
+ *
+ * Inspection never writes: `set` and `remove` are only checked for shape, never invoked, so
+ * `get` alone decides. A candidate pairing an async `get` with a sync `set` satisfies neither
+ * storage interface, which is why proving the other two members is not worth a write.
+ */
 export default function isAsyncStorage(storage: unknown): storage is AsyncStorage {
-    const hasGet = Boolean(storage) && typeof (storage as any)?.get !== 'undefined'
-    const hasSet = Boolean(storage) && typeof (storage as any)?.set !== 'undefined'
-    const hasRemove = Boolean(storage) && typeof (storage as any)?.remove !== 'undefined'
-
-    if (!hasGet || !hasSet || !hasRemove) {
-        return false
-    }
-
-    const hasGetPromise = isPromise((storage as any).get)
-        || isFunction((storage as any).get) && isPromise((storage as any).get(''))
-        || isAsyncFunction((storage as any).get)
-    const hasSetPromise = isPromise((storage as any).set)
-        || isFunction((storage as any).set) && isPromise((storage as any).set({}))
-        || isAsyncFunction((storage as any).set)
-    const hasRemovePromise = isPromise((storage as any).remove)
-        || isFunction((storage as any).remove) && isPromise((storage as any).remove(''))
-        || isAsyncFunction((storage as any).remove)
-
-    return Boolean(storage)
-        && hasGet
-        && hasSet
-        && hasRemove
-        && hasGetPromise
-        && hasSetPromise
-        && hasRemovePromise
+  const candidate = storage as StorageCandidate | null | undefined
+
+  if (!candidate) {
+    return false
+  }
+
+  const { get, set, remove } = candidate
+
+  if (!isCallableMember(set) || !isCallableMember(remove)) {
+    return false
+  }
+
+  // An `async` declaration is the one form of asyncness visible without a call.
+  if (isAsyncFunction(get)) {
+    return true
+  }
+
+  if (!isFunction(get)) {
+    return false
+  }
+
+  // `AsyncStorage` admits a plain function returning a promise, and nothing short of a call tells
+  // that apart from a sync get. Any adapter written that way can only be recognised here, and a
+  // third-party one is free to be written that way, so this line stays necessary however the
+  // shipped adapters happen to declare themselves. A read is the one probe that leaves the
+  // inspected storage as it found it.
+  let probe: unknown
+
+  try {
+    // Called as a method of the storage it belongs to: an adapter written as an
+    // object of methods reads its own state through `this`, and probing the
+    // extracted function would throw on a storage that is perfectly valid.
+    probe = get.call(candidate, '')
+  } catch {
+    // Not swallowed, deferred: consumers build the factory at module scope, where
+    // a throw takes the import down instead of reaching a component. A storage
+    // whose read fails is not provably async, and the sync path raises the same
+    // failure at the first read, where it can be handled.
+    return false
+  }
+
+  if (!isPromise(probe)) {
+    return false
+  }
+
+  // Only the probe's shape answers the question, so its outcome is discarded by construction.
+  // The rejection still has to be claimed: unclaimed, it terminates the process on Node 15+,
+  // letting a storage that merely fails a read take the consuming application down with it.
+  probe.then(undefined, () => undefined)
+
+  return true
 }

package/src/utils/storage-event-router.ts

@@ -0,0 +1,67 @@
+import type { StorageChange } from '../@types/storage'
+
+/** An adapter waiting for DOM storage events about the area it wraps. */
+export interface StorageEventRoute {
+  storage: globalThis.Storage
+  fire(changes: { [key: string]: StorageChange }): void
+}
+
+const routes = new Set<StorageEventRoute>()
+
+let subscription: ((event: StorageEvent) => void) | null = null
+
+function routeStorageEvent(event: StorageEvent): void {
+  if (!event.key) return
+
+  const changes = {
+    [event.key]: {
+      newValue: event.newValue,
+      oldValue: event.oldValue,
+    },
+  }
+
+  for (const route of routes) {
+    // A browser always names the area it changed, so real cross-tab events
+    // reach only the adapter of that area. An event a consumer synthesized —
+    // the sole way to test cross-tab sync under jsdom, and a common way to
+    // notify the writing tab in production — often cannot name one: the
+    // StorageEvent constructor rejects a mocked storage there. Those still go
+    // everywhere, exactly as they did before areas were told apart.
+    if (event.storageArea == null || event.storageArea === route.storage) {
+      route.fire(changes)
+    }
+  }
+}
+
+// A runtime can provide storage without the DOM event API, and can provide half
+// of that API: subscribing where nothing can unsubscribe strands a listener and
+// makes releasing it throw, so both halves are required before taking one.
+function canSubscribe(): boolean {
+  return typeof globalThis.addEventListener === 'function' && typeof globalThis.removeEventListener === 'function'
+}
+
+/**
+ * Starts routing DOM storage events to `route`. Every adapter shares one
+ * subscription on the global object, so creating adapters nobody listens to
+ * costs nothing.
+ */
+export function addRoute(route: StorageEventRoute): void {
+  routes.add(route)
+
+  if (!subscription && canSubscribe()) {
+    subscription = routeStorageEvent
+
+    globalThis.addEventListener('storage', subscription)
+  }
+}
+
+/** Stops routing to `route`, releasing the shared subscription with the last one. */
+export function removeRoute(route: StorageEventRoute): void {
+  routes.delete(route)
+
+  if (routes.size === 0 && subscription) {
+    globalThis.removeEventListener('storage', subscription)
+
+    subscription = null
+  }
+}

package/src/utils/use-storage-handler.ts

@@ -1,62 +1,138 @@
-import React, {useEffect} from 'react'
-import { AsyncStorage, Storage, StorageChange } from '../@types/storage'
-import { isFunction } from '@plq/is'
+import type React from 'react'
+import { useEffect, useRef } from 'react'
+import type { AsyncStorage, Storage, StorageChange } from '../@types/storage'
+import { isFunction, isObject } from '@plq/is'
 
-function getValue<T>(key: string, value: string) {
-  let newState = null
+/**
+ * One key read out of a serialized entry. `null` is a value a caller can store,
+ * so a stored `null` has to stay distinguishable from no value at all —
+ * collapsing the two is what dropped a persisted `null` on its way from a change
+ * event into state.
+ *
+ * A key that is not in the entry and an entry that will not parse are both
+ * `unavailable`. They differ in why, not in what a caller does next, and the
+ * difference that matters is reported where it happens: only a parse failure is
+ * a defect worth a diagnostic, an entry holding other keys is routine.
+ */
+type StoredValue<T> = { status: 'stored'; value: T } | { status: 'unavailable' }
+
+function readStoredValue<T>(key: string, entry: string): StoredValue<T> {
+  let parsed: unknown
 
   try {
-    newState = JSON.parse(value)
+    parsed = JSON.parse(entry)
   } catch (err) {
-    console.error('use-persisted-state: Can\'t parse value from storage', err)
+    console.error("use-persisted-state: Can't parse value from storage", err)
+
+    return { status: 'unavailable' }
   }
 
-  return newState && key in newState ? newState[key] as T : null
+  // A foreign entry can be any JSON value, and `in` throws on a primitive. This
+  // runs inside the adapter's notify loop, where a throw also cuts off every
+  // listener queued behind this one.
+  if (!isObject(parsed) || !(key in parsed)) return { status: 'unavailable' }
+
+  return { status: 'stored', value: parsed[key] as T }
 }
 
-function useStorageHandler<T>(
+// Restores the initial value when the whole entry is removed from the storage.
+function applyRemoval<T>(
+  change: StorageChange,
+  itemKey: string,
+  applyValue: (value: T) => void,
+  latestInitialValue: React.RefObject<T | (() => T)>,
+): void {
+  if (change.oldValue === null || change.oldValue === undefined) return
+
+  const oldValue = readStoredValue<T>(itemKey, change.oldValue)
+  const declaredInitialValue = latestInitialValue.current
+  // Compared against the resolved value: a factory is never equal to what it
+  // produces, so comparing the declaration re-applies the initial value on every
+  // removal.
+  const initialValue = isFunction(declaredInitialValue) ? declaredInitialValue() : declaredInitialValue
+
+  // An entry with no readable value for the key cannot be shown to have held the
+  // initial value, so the fallback is applied rather than skipped. The entry is
+  // gone either way, and stale state left in place is worse than a redundant
+  // restore.
+  if (oldValue.status === 'stored' && oldValue.value === initialValue) return
+
+  applyValue(initialValue)
+}
+
+/**
+ * Reports whether this change is the write the hook itself just made, forgetting
+ * the record when it is. A backend reports a write to every listener, the one
+ * that made it included, and applying that echo is the storage-to-state re-sync
+ * this hook was rebuilt without, arriving by another road: it decodes the entry
+ * again and hands the caller an equal value with a new identity, plus a render
+ * for a value it already holds.
+ *
+ * The price, accepted knowingly: for a value JSON cannot carry, the writer keeps
+ * what it set - NaN - while every other component on the key decodes the null
+ * that reached storage, so the two disagree until one of them remounts. Applying
+ * the echo would settle that disagreement and bring back both the second
+ * storage-to-state path and the render per write, so it is not the repair it
+ * looks like.
+ *
+ * Forgetting on the first match keeps a later identical entry a change. Another
+ * hook writing the same bytes is suppressed along with it, and nothing is lost:
+ * it would have replaced a value with an equal one.
+ */
+function consumeOwnWriteEcho(change: StorageChange, pendingOwnWrite: React.RefObject<string | null>): boolean {
+  if (pendingOwnWrite.current === null || change.newValue !== pendingOwnWrite.current) return false
+
+  pendingOwnWrite.current = null
+
+  return true
+}
+
+// Builds the change handler. Not a hook, despite living next to one.
+function createStorageHandler<T>(
   itemKey: string,
   storageKey: string,
-  setState: React.Dispatch<React.SetStateAction<T>>,
-  initialValue: T | (() => T),
+  applyValue: (value: T) => void,
+  latestInitialValue: React.RefObject<T | (() => T)>,
+  pendingOwnWrite: React.RefObject<string | null>,
 ) {
   return (changes: { [key: string]: StorageChange }): void => {
-    Object.entries(changes).forEach(([key, change]) => {
-      if (
-        key === storageKey
-        && (
-          change.newValue === null || change.newValue === undefined
-        )
-        && change.oldValue !== null
-        && change.oldValue !== undefined
-      ) {
-        const oldValue = getValue<T>(itemKey, change.oldValue)
-
-        if (oldValue !== initialValue) setState(isFunction(initialValue) ? initialValue() : initialValue)
-      }
+    for (const [key, change] of Object.entries(changes)) {
+      if (key !== storageKey) continue
 
-      if (
-        key === storageKey
-        && change.newValue !== null
-        && change.newValue !== undefined
-      ) {
-        const newValue = getValue<T>(itemKey, change.newValue)
+      if (consumeOwnWriteEcho(change, pendingOwnWrite)) continue
 
-        if (newValue !== null) setState(newValue)
+      if (change.newValue === null || change.newValue === undefined) {
+        applyRemoval<T>(change, itemKey, applyValue, latestInitialValue)
+        continue
       }
-    })
+
+      const newValue = readStoredValue<T>(itemKey, change.newValue)
+
+      if (newValue.status === 'stored') applyValue(newValue.value)
+    }
   }
 }
 
-export default function<T>(
+export default function useStorageHandler<T>(
   key: string,
   storageKey: string,
-  setState: React.Dispatch<React.SetStateAction<T>>,
+  applyValue: (value: T) => void,
   storage: AsyncStorage | Storage,
   initialValue: T | (() => T),
+  pendingOwnWrite: React.RefObject<string | null>,
 ): void {
+  // A removal restores the initial value the hook holds now, the same one the
+  // key-change path reads, so a caller whose default travels with its data gets
+  // that record's default back rather than the mounted one. Tracked through a ref
+  // rather than a dependency because an inline object or factory has a new
+  // identity every render, which would tear the subscription down and rebuild it;
+  // written during render, as the key the hook is rendering for is.
+  const latestInitialValue = useRef(initialValue)
+
+  latestInitialValue.current = initialValue
+
   useEffect(() => {
-    const handleStorage = useStorageHandler<T>(key, storageKey, setState, initialValue)
+    const handleStorage = createStorageHandler<T>(key, storageKey, applyValue, latestInitialValue, pendingOwnWrite)
 
     storage.onChanged.addListener(handleStorage)
 
@@ -65,5 +141,5 @@ export default function<T>(
         storage.onChanged.removeListener(handleStorage)
       }
     }
-  }, [initialValue, key, storage.onChanged, storageKey, setState])
+  }, [key, storage.onChanged, storageKey, applyValue, pendingOwnWrite])
 }

package/storages/browser-storage.d.ts

@@ -0,0 +1 @@
+export { local, sync, managed } from '../lib/storages/browser-storage'