@plq/use-persisted-state 1.3.0 → 1.4.1

package/src/create-async-persisted-state.ts

@@ -1,12 +1,13 @@
-import React, {useEffect, useState} from 'react'
+import type React from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 
-import useStorageHandler from './utils/use-storage-handler'
+import useStorageHandler, { recordOwnWrite } from './utils/use-storage-handler'
 import getNewValue from './utils/get-new-value'
 import getNewItem from './utils/get-new-item'
 import getPersistedValue from './utils/get-persisted-value'
 
-import {AsyncStorage} from './@types/storage'
-import {PersistedState, UsePersistedState} from './@types/hook'
+import type { AsyncStorage } from './@types/storage'
+import type { PersistedState, UsePersistedState } from './@types/hook'
 
 export default function createAsyncPersistedState<S extends AsyncStorage>(
   storageKey: string,
@@ -14,37 +15,141 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
 ): [PersistedState, () => Promise<void>] {
   const safeStorageKey = `persisted_state_hook:${storageKey}`
 
+  // Every hook this factory makes lives in one entry, and storing a value means
+  // reading that entry, merging one key into it and writing all of it back, with
+  // a suspension point on either side of the merge. Left to overlap, a second
+  // writer merges into a snapshot taken before the first one landed and stores
+  // it: the first writer's key is gone from storage while its value is still on
+  // screen, and nothing reports the disagreement. It is the entry, not the hook,
+  // that has to be taken one at a time, so the chain belongs to the factory.
+  let entryWrites: Promise<unknown> = Promise.resolve()
+
   const clear = (): Promise<void> => {
-    return storage.remove(safeStorageKey)
+    // Removing the entry changes it as much as storing does, so it takes its turn
+    // in the same chain. Outside it, a write already queued lands after the
+    // removal and brings back what was cleared - and "clear this data" is the one
+    // request that cannot be allowed to half happen.
+    const removal = entryWrites.then(() => storage.remove(safeStorageKey))
+
+    entryWrites = removal.catch(() => undefined)
+
+    return removal
+  }
+
+  const commitEntry = <T>(key: string, newValue: T, pendingOwnWrites: React.RefObject<string[]>): Promise<void> => {
+    const write = entryWrites.then(async () => {
+      const persistedItem = await storage.get(safeStorageKey)
+      let newItem: string
+
+      try {
+        newItem = getNewItem<T>(key, persistedItem[safeStorageKey], newValue)
+      } catch {
+        // Refused, and reported where it was refused. A write replaces the whole
+        // entry, so an entry that cannot be read is one no write can be built on
+        // without dropping every other hook's key; skipping leaves the bytes for
+        // a repair to reach. The caller keeps what it set, unpersisted.
+        return
+      }
+
+      // Recorded before the write, because the backend may report it before the
+      // promise settles.
+      recordOwnWrite(pendingOwnWrites, newItem)
+
+      await storage.set({ [safeStorageKey]: newItem })
+    })
+
+    // The chain has to outlive a failed write, or one backend rejection stops
+    // every later write on this entry. The rejection itself is not swallowed: it
+    // stays on the promise handed back to the caller that asked for the write.
+    entryWrites = write.catch(() => undefined)
+
+    return write
   }
 
   const usePersistedState = <T>(key: string, initialValue: T | (() => T)): UsePersistedState<T> => {
     const [state, setState] = useState<T>(initialValue)
 
-    const setPersistedState = async (newState: React.SetStateAction<T>): Promise<void> => {
-      const newValue = getNewValue<T>(newState, state)
+    // The setter must resolve updater functions against the last value applied,
+    // not against the one captured by the render that created it. Reading the
+    // render closure collapses updates batched into a single event.
+    const latestValue = useRef(state)
 
-      setState(newValue)
+    // Whether anything has already put a value in place. A load that settles after
+    // the caller set one must not revert it, and no signal local to the load can
+    // answer this: the write it loses to happens outside the load entirely.
+    const hasAppliedValue = useRef(false)
 
-      const persistedItem = await storage.get(safeStorageKey)
-      const newItem = getNewItem<T>(key, persistedItem[safeStorageKey], newValue)
+    const applyValue = useCallback((value: T): void => {
+      latestValue.current = value
+      hasAppliedValue.current = true
+
+      setState(value)
+    }, [])
+
+    // The entries this hook has written and not yet seen reported back.
+    const pendingOwnWrites = useRef<string[]>([])
+
+    const setPersistedState = useCallback(
+      async (newState: React.SetStateAction<T>): Promise<void> => {
+        const newValue = getNewValue<T>(newState, latestValue.current)
+
+        // Applied before the write is even queued: the caller sees its value at
+        // once, and only the trip to storage waits its turn.
+        applyValue(newValue)
+
+        await commitEntry<T>(key, newValue, pendingOwnWrites)
+      },
+      [key, applyValue],
+    )
 
-      await storage.set({[safeStorageKey]: newItem})
-    }
+    // As in `useState`, the value the load falls back to is the one given on the
+    // first render. Later identities of an inline object must not reload, or the
+    // effect re-runs on every render and never settles.
+    const mountInitialValue = useRef(initialValue)
+
+    // Subscribed before the load below, and the order is load-bearing: React runs
+    // effects in declaration order, so reading first would leave an interval
+    // between the read and the subscription in which a write belongs to neither
+    // and is lost. Reading last covers everything written before the subscription
+    // began, and the listener covers everything after.
+    useStorageHandler<T>(key, safeStorageKey, applyValue, storage, initialValue, pendingOwnWrites)
 
     useEffect(() => {
-      const setInitialValue = async () => {
-        const persist = await storage.get(safeStorageKey)
-        const persistedState = persist[safeStorageKey]
-        const initialOrPersistedValue = getPersistedValue<T>(key, initialValue, persistedState)
+      // Two separate questions, and one cell cannot hold both: whether this load
+      // is still the current one, which only the closure it belongs to can answer,
+      // and whether a value has been applied meanwhile, which outlives it. A load
+      // abandoned by a key change would otherwise read the flag its successor had
+      // just set, apply the previous key's value and shut the successor out. The
+      // second question is also what makes subscribing first safe: a value the
+      // listener delivers while the load is in flight is not overwritten by it.
+      let isCancelled = false
+
+      hasAppliedValue.current = false
+
+      const loadPersistedValue = async (): Promise<void> => {
+        try {
+          const persist = await storage.get(safeStorageKey)
 
-        setState(initialOrPersistedValue)
+          if (isCancelled || hasAppliedValue.current) return
+
+          applyValue(getPersistedValue<T>(key, mountInitialValue.current, persist[safeStorageKey]))
+        } catch (err) {
+          // An extension backend rejects on a quota error or an invalidated
+          // extension context. Nothing awaits this load, so an unclaimed
+          // rejection terminates the process on Node 15+ and surfaces as an
+          // uncaught error in the browser. The initial value is already in
+          // state, so the mount stands on it and the failure is reported rather
+          // than swallowed, as the synchronous path reports its own.
+          console.error("use-persisted-state: Can't read value from storage", err)
+        }
       }
 
-      setInitialValue()
-    }, [initialValue, key])
+      loadPersistedValue()
 
-    useStorageHandler<T>(key, safeStorageKey, setState, storage, initialValue)
+      return () => {
+        isCancelled = true
+      }
+    }, [key, applyValue])
 
     return [state, setPersistedState]
   }

package/src/create-persisted-state.ts

@@ -1,47 +1,83 @@
-import React, {useEffect, useState} from 'react'
+import type React from 'react'
+import { useCallback, useRef, useState } from 'react'
 
-import {Storage} from './@types/storage'
-import {PersistedState, UsePersistedState} from './@types/hook'
+import type { Storage } from './@types/storage'
+import type { PersistedState, UsePersistedState } from './@types/hook'
 
-import useStorageHandler from './utils/use-storage-handler'
+import useStorageHandler, { recordOwnWrite } from './utils/use-storage-handler'
 import getNewValue from './utils/get-new-value'
 import getNewItem from './utils/get-new-item'
 import getPersistedValue from './utils/get-persisted-value'
 
-export default function createPersistedState(
-  storageKey: string,
-  storage: Storage,
-): [PersistedState, () => void] {
+export default function createPersistedState(storageKey: string, storage: Storage): [PersistedState, () => void] {
   const safeStorageKey = `persisted_state_hook:${storageKey}`
   const clear = (): void => {
     storage.remove(safeStorageKey)
   }
 
+  const readPersisted = <T>(key: string, initialValue: T): T =>
+    getPersistedValue<T>(key, initialValue, storage.get(safeStorageKey)[safeStorageKey])
+
   const usePersistedState = <T>(key: string, initialValue: T): UsePersistedState<T> => {
-    const persist = storage.get(safeStorageKey)
-    const persistedState = persist[safeStorageKey]
-    const initialOrPersistedValue = getPersistedValue<T>(key, initialValue, persistedState)
+    // Reading through the initializer keeps the storage out of the render path:
+    // the hook runs on every render of every consuming component, so a re-read is
+    // only warranted when the key it is asked for actually changes.
+    const [state, setState] = useState<T>(() => readPersisted(key, initialValue))
+
+    // The setter must resolve updater functions against the last value applied,
+    // not against the one captured by the render that created it. Reading the
+    // render closure collapses updates batched into a single event.
+    const latestValue = useRef(state)
 
-    const [state, setState] = useState<T>(initialOrPersistedValue)
+    const applyValue = useCallback((value: T): void => {
+      latestValue.current = value
 
-    const setPersistedState = (newState: React.SetStateAction<T>): void => {
-      const newValue = getNewValue<T>(newState, state)
+      setState(value)
+    }, [])
 
-      setState(newValue)
+    // A mounted hook handed a different key has to show that key's value before
+    // anything can be written, or the next update stores the previous key's value
+    // under the new key and destroys what was there. Adjusting during render ties
+    // the re-read to the change itself, where an effect would cost a read and a
+    // second render on every mount as well.
+    const renderedKey = useRef(key)
 
-      const persistedItem = storage.get(safeStorageKey)[safeStorageKey]
-      const newItem = getNewItem<T>(key, persistedItem, newValue)
+    if (renderedKey.current !== key) {
+      renderedKey.current = key
 
-      storage.set({[safeStorageKey]: newItem})
+      applyValue(readPersisted(key, initialValue))
     }
 
-    useEffect(() => {
-      const initialOrPersistedValue = getPersistedValue<T>(key, initialValue, persistedState)
+    // The entries this hook has written and not yet seen reported back.
+    const pendingOwnWrites = useRef<string[]>([])
+
+    const setPersistedState = useCallback(
+      (newState: React.SetStateAction<T>): void => {
+        const newValue = getNewValue<T>(newState, latestValue.current)
+
+        applyValue(newValue)
+
+        const persistedItem = storage.get(safeStorageKey)[safeStorageKey]
+        let newItem: string
+
+        try {
+          newItem = getNewItem<T>(key, persistedItem, newValue)
+        } catch {
+          // Refused, and reported where it was refused. A write replaces the whole
+          // entry, so an entry that cannot be read is one no write can be built on
+          // without dropping every other hook's key; skipping leaves the bytes for
+          // a repair to reach. The caller keeps what it set, unpersisted.
+          return
+        }
+
+        recordOwnWrite(pendingOwnWrites, newItem)
 
-      setState(initialOrPersistedValue)
-    }, [initialValue, key, persistedState])
+        storage.set({ [safeStorageKey]: newItem })
+      },
+      [key, applyValue],
+    )
 
-    useStorageHandler<T>(key, safeStorageKey, setState, storage, initialValue)
+    useStorageHandler<T>(key, safeStorageKey, applyValue, storage, initialValue, pendingOwnWrites)
 
     return [state, setPersistedState]
   }

package/src/index.ts

@@ -1,10 +1,10 @@
-import { default as createSyncPersistedState } from './create-persisted-state'
+import createSyncPersistedState from './create-persisted-state'
 import createAsyncPersistedState from './create-async-persisted-state'
 
 import isAsyncStorage from './utils/is-async-storage'
 
-import { Storage, AsyncStorage } from './@types/storage'
-import { PersistedState } from './@types/hook'
+import type { Storage, AsyncStorage } from './@types/storage'
+import type { PersistedState } from './@types/hook'
 
 export default function createPersistedState<S extends Storage | AsyncStorage>(
   name: string,
@@ -17,7 +17,12 @@ export default function createPersistedState<S extends Storage | AsyncStorage>(
   return createSyncPersistedState(name, storage as Storage)
 }
 
-export {
-  createSyncPersistedState as createPersistedState,
-  createAsyncPersistedState,
-}
+export { default as createPersistedState } from './create-persisted-state'
+export { default as createAsyncPersistedState } from './create-async-persisted-state'
+
+// The contract a backend implements, and the shape the hook hands back. Both appear in the
+// signatures above, so a consumer writing an adapter or typing a wrapper has to be able to name
+// them from the supported entry point rather than from `lib/`, which the exports map keeps open
+// only as a frozen legacy path.
+export type { AsyncStorage, Storage, StorageChange, StorageChangeEvent, StorageChangeListener } from './@types/storage'
+export type { PersistedState, UsePersistedState } from './@types/hook'

package/src/storages/browser-storage.ts

@@ -1,50 +1,22 @@
-import { AsyncStorage, StorageChange, StorageChangeEvent, StorageChangeListener } from '../@types/storage'
+import type { AsyncStorage } from '../@types/storage'
+import { type Area, createListenerRegistry, toStorageChanges, toStoredItems } from '../utils/extension-storage'
 
-const listeners = {
-  local: new Set<StorageChangeListener>(),
-  sync: new Set<StorageChangeListener>(),
-  managed: new Set<StorageChangeListener>(),
-}
-
-type Area = keyof typeof listeners
-
-function fireStorageEvent(changes: { [key: string]: StorageChange }, area: Area) {
-  listeners[area].forEach(listener => {
-    listener(changes)
-  })
-}
+const registry = createListenerRegistry()
 
 browser.storage.onChanged.addListener((changes, area) => {
-  fireStorageEvent(changes, area as Area)
+  registry.fire(toStorageChanges(changes), area)
 })
 
-function createOnChanged(area: Area): StorageChangeEvent {
-  return {
-    addListener(listener) {
-      listeners[area].add(listener)
-    },
-    removeListener(listener) {
-      listeners[area].delete(listener)
-    },
-    hasListener(listener) {
-      return listeners[area].has(listener)
-    },
-  }
-}
-
+// browser.storage is promise-based, unlike its callback-based chrome counterpart.
 const createStorage = (storage: browser.storage.StorageArea, area: Area): AsyncStorage => ({
-  get: storage.get,
+  get: async keys => toStoredItems(await storage.get(keys)),
   set: storage.set,
   remove: storage.remove,
-  onChanged: createOnChanged(area),
+  onChanged: registry.createOnChanged(area),
 })
 
 const local = createStorage(browser.storage.local, 'local')
 const sync = createStorage(browser.storage.sync, 'sync')
 const managed = createStorage(browser.storage.managed, 'managed')
 
-export {
-  local,
-  sync,
-  managed,
-}
+export { local, sync, managed }

package/src/storages/chrome-storage.ts

@@ -1,58 +1,36 @@
-import { AsyncStorage, StorageChange, StorageChangeEvent, StorageChangeListener } from '../@types/storage'
+import type { AsyncStorage } from '../@types/storage'
+import { type Area, createListenerRegistry, toStorageChanges, toStoredItems } from '../utils/extension-storage'
 
-const listeners = {
-  local: new Set<StorageChangeListener>(),
-  sync: new Set<StorageChangeListener>(),
-  managed: new Set<StorageChangeListener>(),
-}
-
-type Area = keyof typeof listeners
-
-function fireStorageEvent(changes: { [key: string]: StorageChange }, area: Area) {
-  listeners[area].forEach(listener => {
-    listener(changes)
-  })
-}
+const registry = createListenerRegistry()
 
 chrome.storage.onChanged.addListener((changes, area) => {
-  fireStorageEvent(changes, area as Area)
+  registry.fire(toStorageChanges(changes), area)
 })
 
-function createOnChanged(area: Area): StorageChangeEvent {
-  return {
-    addListener(listener) {
-      listeners[area].add(listener)
-    },
-    removeListener(listener) {
-      listeners[area].delete(listener)
-    },
-    hasListener(listener) {
-      return listeners[area].has(listener)
-    },
-  }
-}
-
+// chrome.storage is callback-based, unlike its promise-based firefox counterpart.
 const createStorage = (storage: chrome.storage.StorageArea, area: Area): AsyncStorage => ({
-  get: keys => new Promise(resolve => {
-    storage.get(keys, items => {
-      resolve(items)
-    })
-  }),
-  set: items => new Promise(resolve => {
-    storage.set(items, resolve)
-  }),
-  remove: keys => new Promise(resolve => {
-    storage.remove(keys, resolve)
-  }),
-  onChanged: createOnChanged(area),
+  // Declared async, like the firefox adapter, so that asking whether this
+  // storage is asynchronous can be answered from the function itself instead of
+  // by calling it — a call here costs a round trip to the extension process.
+  get: async keys =>
+    new Promise(resolve => {
+      storage.get(keys, items => {
+        resolve(toStoredItems(items))
+      })
+    }),
+  set: items =>
+    new Promise(resolve => {
+      storage.set(items, resolve)
+    }),
+  remove: keys =>
+    new Promise(resolve => {
+      storage.remove(keys, resolve)
+    }),
+  onChanged: registry.createOnChanged(area),
 })
 
 const local = createStorage(chrome.storage.local, 'local')
 const sync = createStorage(chrome.storage.sync, 'sync')
 const managed = createStorage(chrome.storage.managed, 'managed')
 
-export {
-  local,
-  sync,
-  managed,
-}
+export { local, sync, managed }

package/src/storages/local-storage.ts

@@ -1,3 +1,5 @@
 import createStorage from '../utils/create-web-storage'
 
-export default createStorage(localStorage)
+// The typeof guard keeps this import from throwing on server runtimes (SSR),
+// where the browser storage globals are not defined.
+export default createStorage(typeof localStorage !== 'undefined' ? localStorage : undefined)

package/src/storages/session-storage.ts

@@ -1,3 +1,5 @@
 import createStorage from '../utils/create-web-storage'
 
-export default createStorage(sessionStorage)
+// The typeof guard keeps this import from throwing on server runtimes (SSR),
+// where the browser storage globals are not defined.
+export default createStorage(typeof sessionStorage !== 'undefined' ? sessionStorage : undefined)

package/src/utils/change-notifier.ts

@@ -0,0 +1,43 @@
+import type { StorageChange, StorageChangeEvent, StorageChangeListener } from '../@types/storage'
+
+export interface ChangeNotifier {
+  fire(changes: { [key: string]: StorageChange }): void
+  hasListeners(): boolean
+  onChanged: StorageChangeEvent
+}
+
+/**
+ * Holds the subscribers of a single change source. Each adapter — and, for the
+ * extension backends, each storage area — owns one, so a change never reaches
+ * listeners that subscribed elsewhere.
+ *
+ * Routing a backend's events to the right notifier stays with the adapter: the
+ * extensions demultiplex one event by area name, the DOM one by storage object.
+ */
+export function createChangeNotifier(): ChangeNotifier {
+  const listeners = new Set<StorageChangeListener>()
+
+  return {
+    fire(changes) {
+      for (const listener of listeners) {
+        listener(changes)
+      }
+    },
+    // Lets an adapter release a shared resource once nobody is listening; the
+    // set behind onChanged stays the only count, so the two cannot drift.
+    hasListeners() {
+      return listeners.size > 0
+    },
+    onChanged: {
+      addListener(listener) {
+        listeners.add(listener)
+      },
+      removeListener(listener) {
+        listeners.delete(listener)
+      },
+      hasListener(listener) {
+        return listeners.has(listener)
+      },
+    },
+  }
+}