@plq/use-persisted-state 1.3.0 → 1.4.1

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,16 +1,39 @@
-export default function<T>(key: string, persistedItem: string, newValue: T): string {
-  let persist: { [x: string]: unknown }
+import { isObject } from '@plq/is'
+
+/**
+ * Merges `newValue` under `key` into the serialized entry a factory shares between all of its
+ * hooks, and returns the entry to store.
+ *
+ * Reports and throws when the entry cannot be merged into, rather than answering with one built
+ * from nothing. What this returns is written over the whole entry, so an unreadable entry is the
+ * one case with nothing safe to return: every other hook's key would be replaced with nothing,
+ * and the bytes a repair still needs would go with them.
+ *
+ * @throws {SyntaxError} when the entry is not valid JSON.
+ * @throws {TypeError} when the entry is valid JSON but not an object of keys.
+ */
+export default function getNewItem<T>(key: string, persistedItem: string, newValue: T): string {
+  let persist: unknown
 
   try {
     persist = persistedItem ? JSON.parse(persistedItem) : {}
   } catch (err) {
-    console.error(err)
-    persist = {}
+    console.error("use-persisted-state: Can't write value to storage", err)
+
+    throw err
+  }
+
+  if (!isObject(persist)) {
+    // A shared backend can leave any JSON under the key, and neither a primitive nor an array
+    // survives being merged into: `JSON.stringify` unwraps the first back to itself and keeps the
+    // second an array, so the value being set disappears with the property added to it. A stored
+    // `null` did not even get that far - it threw out of `Object.assign` and into the caller.
+    const err = new TypeError('the stored entry is not an object of keys')
+
+    console.error("use-persisted-state: Can't write value to storage", err)
+
+    throw err
   }
 
-  return JSON.stringify(
-    Object.assign(persist, {
-      [key]: newValue,
-    }),
-  )
+  return JSON.stringify({ ...persist, [key]: newValue })
 }

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
+  }
+}