@plq/use-persisted-state 1.2.0 → 1.4.0

package/package.json

@@ -1,47 +1,110 @@
 {
   "name": "@plq/use-persisted-state",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "useState hook with persistence in storage",
+  "type": "commonjs",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "default": "./lib/index.js"
+    },
+    "./storages/local-storage": {
+      "import": {
+        "types": "./esm/storages/local-storage.d.mts",
+        "default": "./esm/storages/local-storage.mjs"
+      },
+      "require": {
+        "types": "./lib/storages/local-storage.d.ts",
+        "default": "./lib/storages/local-storage.js"
+      },
+      "default": "./lib/storages/local-storage.js"
+    },
+    "./storages/session-storage": {
+      "import": {
+        "types": "./esm/storages/session-storage.d.mts",
+        "default": "./esm/storages/session-storage.mjs"
+      },
+      "require": {
+        "types": "./lib/storages/session-storage.d.ts",
+        "default": "./lib/storages/session-storage.js"
+      },
+      "default": "./lib/storages/session-storage.js"
+    },
+    "./storages/browser-storage": {
+      "import": {
+        "types": "./esm/storages/browser-storage.d.mts",
+        "default": "./esm/storages/browser-storage.mjs"
+      },
+      "require": {
+        "types": "./lib/storages/browser-storage.d.ts",
+        "default": "./lib/storages/browser-storage.js"
+      },
+      "default": "./lib/storages/browser-storage.js"
+    },
+    "./storages/chrome-storage": {
+      "import": {
+        "types": "./esm/storages/chrome-storage.d.mts",
+        "default": "./esm/storages/chrome-storage.mjs"
+      },
+      "require": {
+        "types": "./lib/storages/chrome-storage.d.ts",
+        "default": "./lib/storages/chrome-storage.js"
+      },
+      "default": "./lib/storages/chrome-storage.js"
+    },
+    "./lib": "./lib/index.js",
+    "./lib/*.js": "./lib/*.js",
+    "./lib/*": "./lib/*.js",
+    "./src": "./src/index.ts",
+    "./src/*.ts": "./src/*.ts",
+    "./src/*": "./src/*.ts",
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=16.0.0"
   },
   "files": [
     "/src",
     "/lib",
+    "/esm",
+    "/storages",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
     "build:watch": "tsc --watch",
     "build:types": "tsc --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "test": "jest --verbose",
+    "test:random": "jest --randomize --showSeed",
     "test:watch": "npm test -- --watchAll",
-    "lint": "eslint ./src/**/*.ts",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "check:package": "node scripts/check-package.mjs",
+    "check:publint": "npx --yes publint",
+    "check:attw": "npx --yes @arethetypeswrong/cli --pack . --exclude-entrypoints lib",
+    "check:smoke": "node scripts/smoke.mjs",
+    "check:types": "tsc -p tsconfig.package.json --noEmit",
+    "prepublishOnly": "npm run build",
+    "format": "biome format --write",
     "release": "dotenv release-it",
-    "examples": "npm run build:watch & parcel examples/index.html"
+    "demo": "vite",
+    "demo:build": "vite build",
+    "demo:preview": "vite preview"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Akurganow/use-persisted-state.git"
   },
-  "release-it": {
-    "hooks": {
-      "before:init": [
-        "npm run lint",
-        "npm test",
-        "npm run build"
-      ],
-      "after:release": "echo Successfully released ${name} v${version} to ${repo.repository}."
-    },
-    "plugins": {
-      "@release-it/conventional-changelog": {
-        "preset": "conventionalcommits",
-        "infile": "CHANGELOG.md"
-      }
-    }
-  },
   "keywords": [
     "react",
     "hook",
@@ -52,8 +115,9 @@
     "persist",
     "sync"
   ],
-  "author": "Alex Kurganov <me@akurganow.ru>",
+  "author": "Alexander Kurganov <a.kurganow@gmail.com>",
   "license": "MIT",
+  "funding": "https://ko-fi.com/akurganow",
   "publishConfig": {
     "access": "public"
   },
@@ -62,31 +126,28 @@
   },
   "homepage": "https://github.com/Akurganow/use-persisted-state#readme",
   "devDependencies": {
-    "@release-it/conventional-changelog": "^7.0.2",
-    "@testing-library/jest-dom": "^6.1.3",
-    "@testing-library/react": "^14.0.0",
-    "@types/chrome": "0.0.246",
-    "@types/firefox-webext-browser": "^111.0.2",
-    "@types/jest": "^29.5.5",
-    "@types/react": "^18.2.25",
-    "@typescript-eslint/eslint-plugin": "^6.7.4",
-    "@typescript-eslint/parser": "^6.7.4",
-    "conventional-changelog-cli": "^4.1.0",
-    "dotenv-cli": "^7.3.0",
-    "eslint": "^8.51.0",
-    "eslint-plugin-jest": "^27.2.1",
-    "eslint-plugin-react": "^7.21.5",
-    "eslint-plugin-react-hooks": "^4.2.0",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
+    "@biomejs/biome": "^2.5.6",
+    "@release-it/conventional-changelog": "^12.0.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/chrome": "^0.2.2",
+    "@types/firefox-webext-browser": "^143.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "dotenv-cli": "^11.0.0",
+    "jest": "^30.0.5",
+    "jest-environment-jsdom": "^30.0.5",
     "jest-localstorage-mock": "^2.4.6",
-    "jest-webextension-mock": "^3.7.6",
-    "parcel": "^2.9.3",
-    "process": "^0.11.10",
-    "react-test-renderer": "^18.2.0",
-    "release-it": "^16.2.1",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.2.2"
+    "jest-webextension-mock": "^4.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "release-it": "^21.0.0",
+    "ts-jest": "^29.4.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.2.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",

package/src/@types/storage.ts

@@ -1,26 +1,26 @@
 export interface StorageChange {
-  oldValue?: string | null;
-  newValue?: string | null;
+  oldValue?: string | null
+  newValue?: string | null
 }
 
 export type StorageChangeListener = (changes: { [key: string]: StorageChange }) => void
 
 export interface StorageChangeEvent {
-  addListener(listener: StorageChangeListener): void;
-  removeListener(listener: StorageChangeListener): void;
-  hasListener(listener: StorageChangeListener): boolean;
+  addListener(listener: StorageChangeListener): void
+  removeListener(listener: StorageChangeListener): void
+  hasListener(listener: StorageChangeListener): boolean
 }
 
 export interface Storage {
-  get: (keys: string | string[]) => { [key: string]: string };
-  set: (items: { [key: string]: string }) => void;
-  remove: (keys: string | string[]) => void;
-  onChanged: StorageChangeEvent;
+  get: (keys: string | string[]) => { [key: string]: string }
+  set: (items: { [key: string]: string }) => void
+  remove: (keys: string | string[]) => void
+  onChanged: StorageChangeEvent
 }
 
 export interface AsyncStorage {
-  get: (keys: string | string[]) => Promise<{ [key: string]: string }>;
-  set: (items: { [key: string]: string }) => Promise<void>;
-  remove: (keys: string | string[]) => Promise<void>;
-  onChanged: StorageChangeEvent;
+  get: (keys: string | string[]) => Promise<{ [key: string]: string }>
+  set: (items: { [key: string]: string }) => Promise<void>
+  remove: (keys: string | string[]) => Promise<void>
+  onChanged: StorageChangeEvent
 }

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 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,
@@ -21,30 +22,92 @@ export default function createAsyncPersistedState<S extends AsyncStorage>(
   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
 
-      await storage.set({[safeStorageKey]: newItem})
-    }
+      setState(value)
+    }, [])
+
+    // The exact entry this hook last wrote and has not yet seen reported back.
+    const pendingOwnWrite = useRef<string | null>(null)
+
+    const setPersistedState = useCallback(
+      async (newState: React.SetStateAction<T>): Promise<void> => {
+        const newValue = getNewValue<T>(newState, latestValue.current)
+
+        applyValue(newValue)
+
+        const persistedItem = await storage.get(safeStorageKey)
+        const newItem = getNewItem<T>(key, persistedItem[safeStorageKey], newValue)
+
+        // Recorded before the write, because the backend may report it before the
+        // promise settles.
+        pendingOwnWrite.current = newItem
+
+        await storage.set({ [safeStorageKey]: newItem })
+      },
+      [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.
+    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, pendingOwnWrite)
 
     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
 
-        setState(initialOrPersistedValue)
+      const loadPersistedValue = async (): Promise<void> => {
+        try {
+          const persist = await storage.get(safeStorageKey)
+
+          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,73 @@
-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 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 exact entry this hook last wrote and has not yet seen reported back.
+    const pendingOwnWrite = useRef<string | null>(null)
+
+    const setPersistedState = useCallback(
+      (newState: React.SetStateAction<T>): void => {
+        const newValue = getNewValue<T>(newState, latestValue.current)
+
+        applyValue(newValue)
+
+        const persistedItem = storage.get(safeStorageKey)[safeStorageKey]
+        const newItem = getNewItem<T>(key, persistedItem, newValue)
+
+        pendingOwnWrite.current = 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, pendingOwnWrite)
 
     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)