@plq/use-persisted-state 1.4.1 → 1.4.3

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

@@ -1,7 +1,7 @@
 import type React from 'react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
-import useStorageHandler, { recordOwnWrite } from './utils/use-storage-handler'
+import useStorageHandler 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'
@@ -15,20 +15,11 @@ 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.
+  // Storing is read-merge-write on one shared entry, so overlapping writers would drop each other's keys.
   let entryWrites: Promise<unknown> = Promise.resolve()
 
   const clear = (): Promise<void> => {
-    // 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.
+    // In the same chain as writes, or a queued write lands after the removal and restores what was cleared.
     const removal = entryWrites.then(() => storage.remove(safeStorageKey))
 
     entryWrites = removal.catch(() => undefined)
@@ -36,7 +27,7 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
     return removal
   }
 
-  const commitEntry = <T>(key: string, newValue: T, pendingOwnWrites: React.RefObject<string[]>): Promise<void> => {
+  const commitEntry = <T>(key: string, newValue: T): Promise<void> => {
     const write = entryWrites.then(async () => {
       const persistedItem = await storage.get(safeStorageKey)
       let newItem: string
@@ -44,23 +35,14 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
       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.
+        // A write replaces the whole entry, so an unreadable one is skipped rather than rebuilt without other keys.
         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.
+    // The chain must outlive a failed write; the rejection still reaches the caller through `write`.
     entryWrites = write.catch(() => undefined)
 
     return write
@@ -69,14 +51,10 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
   const usePersistedState = <T>(key: string, initialValue: T | (() => T)): UsePersistedState<T> => {
     const [state, setState] = useState<T>(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.
+    // Updater functions must resolve against the last applied value, not the render closure's.
     const latestValue = useRef(state)
 
-    // 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.
+    // A load that settles after the caller set a value must not revert it.
     const hasAppliedValue = useRef(false)
 
     const applyValue = useCallback((value: T): void => {
@@ -86,42 +64,25 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
       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)
+        await commitEntry<T>(key, newValue)
       },
       [key, applyValue],
     )
 
-    // 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.
+    // The first render's initial value: reloading on a later identity would re-run the effect forever.
     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)
+    // Subscribed before the load: effects run in declaration order, and reading first would lose writes in between.
+    useStorageHandler<T>(key, safeStorageKey, applyValue, storage, initialValue)
 
     useEffect(() => {
-      // 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.
+      // Separate from `hasAppliedValue`: only this closure knows whether its own load is still current.
       let isCancelled = false
 
       hasAppliedValue.current = false
@@ -134,12 +95,7 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
 
           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.
+          // Nothing awaits this load, so an unclaimed rejection would surface as an uncaught error.
           console.error("use-persisted-state: Can't read value from storage", err)
         }
       }

package/src/create-persisted-state.ts

@@ -4,7 +4,7 @@ import { useCallback, useRef, useState } from 'react'
 import type { Storage } from './@types/storage'
 import type { PersistedState, UsePersistedState } from './@types/hook'
 
-import useStorageHandler, { recordOwnWrite } from './utils/use-storage-handler'
+import useStorageHandler 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'
@@ -19,14 +19,10 @@ export default function createPersistedState(storageKey: string, storage: Storag
     getPersistedValue<T>(key, initialValue, storage.get(safeStorageKey)[safeStorageKey])
 
   const usePersistedState = <T>(key: string, initialValue: T): UsePersistedState<T> => {
-    // 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.
+    // Read through the initializer: the hook runs on every render, so storage stays out of the render path.
     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.
+    // Updater functions must resolve against the last applied value, not the render closure's.
     const latestValue = useRef(state)
 
     const applyValue = useCallback((value: T): void => {
@@ -35,11 +31,7 @@ export default function createPersistedState(storageKey: string, storage: Storag
       setState(value)
     }, [])
 
-    // 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.
+    // A new key must be read before anything is written, or the next update stores the old key's value under it.
     const renderedKey = useRef(key)
 
     if (renderedKey.current !== key) {
@@ -48,9 +40,6 @@ export default function createPersistedState(storageKey: string, storage: Storag
       applyValue(readPersisted(key, initialValue))
     }
 
-    // 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)
@@ -63,21 +52,16 @@ export default function createPersistedState(storageKey: string, storage: Storag
         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.
+          // A write replaces the whole entry, so an unreadable one is skipped rather than rebuilt without other keys.
           return
         }
 
-        recordOwnWrite(pendingOwnWrites, newItem)
-
         storage.set({ [safeStorageKey]: newItem })
       },
       [key, applyValue],
     )
 
-    useStorageHandler<T>(key, safeStorageKey, applyValue, storage, initialValue, pendingOwnWrites)
+    useStorageHandler<T>(key, safeStorageKey, applyValue, storage, initialValue)
 
     return [state, setPersistedState]
   }

package/src/index.ts

@@ -20,9 +20,6 @@ export default function createPersistedState<S extends Storage | AsyncStorage>(
 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.
+// Both appear in the signatures above, so a consumer writing an adapter can name them from the entry point.
 export type { AsyncStorage, Storage, StorageChange, StorageChangeEvent, StorageChangeListener } from './@types/storage'
 export type { PersistedState, UsePersistedState } from './@types/hook'

package/src/storages/chrome-storage.ts

@@ -7,25 +7,13 @@ chrome.storage.onChanged.addListener((changes, area) => {
   registry.fire(toStorageChanges(changes), area)
 })
 
-// chrome.storage is callback-based, unlike its promise-based firefox counterpart.
+// Passing no callback selects the promise form; the callback form leaves failures in `runtime.lastError`.
+// Called through `storage`: a torn-off `StorageArea` method throws `Illegal invocation`, unlike firefox's.
+// `get` stays `async` so asking whether this storage is asynchronous costs no round trip to the extension.
 const createStorage = (storage: chrome.storage.StorageArea, area: Area): AsyncStorage => ({
-  // 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)
-    }),
+  get: async keys => toStoredItems(await storage.get(keys)),
+  set: items => storage.set(items),
+  remove: keys => storage.remove(keys),
   onChanged: registry.createOnChanged(area),
 })
 

package/src/storages/local-storage.ts

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

package/src/storages/session-storage.ts

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

package/src/utils/change-notifier.ts

@@ -6,14 +6,7 @@ export interface ChangeNotifier {
   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.
- */
+/** Holds the subscribers of a single change source, so a change never reaches listeners that subscribed elsewhere. */
 export function createChangeNotifier(): ChangeNotifier {
   const listeners = new Set<StorageChangeListener>()
 
@@ -23,8 +16,6 @@ export function createChangeNotifier(): ChangeNotifier {
         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
     },

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

@@ -6,21 +6,12 @@ function toKeyList(keys: string | string[]): string[] {
   return Array.isArray(keys) ? keys : [keys]
 }
 
-/**
- * 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.
- */
+/** Adapts a Web Storage area. With `undefined`, as on a server, it reads back nothing and discards every write. */
 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.
+  // Per instance: the localStorage and sessionStorage adapters must not share listeners.
   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.
+  // Only a missing global is inert; anything else a caller passes has to fail on first use.
   if (storage === undefined) {
     return {
       get: () => ({}),
@@ -32,9 +23,7 @@ export default (storage: globalThis.Storage | undefined): Storage => {
 
   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.
+  // The DOM subscription is shared and reference counted, so adapters nobody listens to attach nothing.
   const onChanged: StorageChangeEvent = {
     addListener(listener) {
       notifier.onChanged.addListener(listener)
@@ -58,8 +47,7 @@ export default (storage: globalThis.Storage | undefined): Storage => {
       for (const key of toKeyList(keys)) {
         const item = storage.getItem(key)
 
-        // `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.
+        // `null` is the only answer meaning absence; an empty string is a value the caller stored.
         if (item !== null) result[key] = item
       }
 

package/src/utils/extension-storage.ts

@@ -5,18 +5,12 @@ 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.
+// Both browsers also report `session`, an area this library does not expose; dispatching one would 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.
- */
+/** Extension storage holds arbitrary JSON; this library writes only strings, so anything else reads as absent. */
 export function toStoredValue(value: unknown): string | null | undefined {
   if (value === undefined) return
 
@@ -53,12 +47,7 @@ export interface ListenerRegistry {
   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.
- */
+/** Demultiplexes an extension's single `onChanged` event to one notifier per area, one registry per adapter. */
 export function createListenerRegistry(): ListenerRegistry {
   const notifiers: { [area in Area]: ChangeNotifier } = {
     local: createChangeNotifier(),

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

@@ -1,17 +1,6 @@
 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.
- */
+/** Merges `newValue` under `key` into the shared entry, throwing rather than rebuilding one it cannot read. */
 export default function getNewItem<T>(key: string, persistedItem: string, newValue: T): string {
   let persist: unknown
 
@@ -24,10 +13,7 @@ export default function getNewItem<T>(key: string, persistedItem: string, newVal
   }
 
   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.
+    // Neither a primitive nor an array survives being merged into: the value being set would disappear.
     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)

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

@@ -1,21 +1,13 @@
 import { isFunction, isObject } from '@plq/is'
 
-/**
- * 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.
- */
+/** Resolves a hook's starting value by key presence, so a persisted `null` is not mistaken for an absence. */
 export default function getPersistedValue<T>(key: string, initialValue: T | (() => T), persist?: string): T {
   let initialPersist: unknown
 
   try {
     initialPersist = persist ? JSON.parse(persist) : {}
   } 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.
+    // A shared backend can hold a foreign or truncated entry, so a parse failure must not stop the mount.
     console.error("use-persisted-state: Can't parse value from storage", err)
 
     initialPersist = {}
@@ -23,9 +15,7 @@ export default function getPersistedValue<T>(key: string, initialValue: T | (()
 
   let initialOrPersistedValue = isFunction(initialValue) ? initialValue() : initialValue
 
-  // `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.
+  // `in` throws on a primitive, and this runs in the `useState` initializer, where a throw stops the mount.
   if (isObject(initialPersist) && key in initialPersist) {
     initialOrPersistedValue = initialPersist[key] as T
   }

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

@@ -1,25 +1,16 @@
 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.
+// `@plq/is` classifies async functions as their own type, so `isFunction` alone rejects them.
 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.
- */
+/** Narrows a storage to {@link AsyncStorage}. Inspecting never writes: `set` and `remove` are never called. */
 export default function isAsyncStorage(storage: unknown): storage is AsyncStorage {
   const candidate = storage as StorageCandidate | null | undefined
 
@@ -42,23 +33,14 @@ export default function isAsyncStorage(storage: unknown): storage is AsyncStorag
     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.
+  // A plain function returning a promise is a valid `AsyncStorage`, and only a call tells it from a sync get.
   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.
+    // Called as a method: an adapter reading its own state through `this` would throw on a torn-off function.
     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.
+    // Deferred, not swallowed: factories are built at module scope, where a throw takes the import down.
     return false
   }
 
@@ -66,9 +48,7 @@ export default function isAsyncStorage(storage: unknown): storage is AsyncStorag
     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.
+  // An unclaimed rejection terminates the process on Node 15+, so the discarded probe still has to be claimed.
   probe.then(undefined, () => undefined)
 
   return true

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

@@ -21,30 +21,19 @@ function routeStorageEvent(event: StorageEvent): void {
   }
 
   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.
+    // An event a consumer synthesized often cannot name an area, so those still reach every route.
     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.
+// A runtime can provide half the DOM event API, and subscribing where nothing can unsubscribe strands a listener.
 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.
- */
+/** Starts routing DOM storage events to `route`. Every adapter shares one subscription on the global object. */
 export function addRoute(route: StorageEventRoute): void {
   routes.add(route)