@plq/use-persisted-state 1.3.0 → 1.4.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Uploadcare
+Copyright (c) 2019 Alexander Kurganov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,21 +1,37 @@
 # usePersistedState
+
 [![npm version](https://badge.fury.io/js/@plq%2Fuse-persisted-state.svg)](https://www.npmjs.com/package/@plq/use-persisted-state)
-[![Tests](https://github.com/Akurganow/use-persisted-state/actions/workflows/main.yml/badge.svg?branch=master)](https://github.com/Akurganow/use-persisted-state/actions/workflows/main.yml)
+[![Tests](https://github.com/Akurganow/use-persisted-state/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/Akurganow/use-persisted-state/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-support-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/akurganow)
 
-Persists the state to localStorage, sessionStorage or any custom storage
+A React `useState` that persists to `localStorage`, `sessionStorage`, extension storage (`browser.storage` / `chrome.storage`), or any custom backend.
 
 ## Features
 
-- Persist the state to `localStorage`, `sessionStorage` or almost anything else implements [storage API](https://github.com/Akurganow/use-persisted-state/blob/master/docs/storage-api.md)
-- The state factory takes as many keys as needed, so you don't have to call the factory for each variable
-- Written with the TypeScript, the definitions go with the library
-- No third-party dependencies
+- Persist state to `localStorage`, `sessionStorage`, extension storage, or almost anything else that implements the [storage API](https://github.com/Akurganow/use-persisted-state/blob/main/docs/storage-api.md)
+- One state factory serves as many keys as needed, so you don't have to call the factory for each variable
+- Supports both synchronous and asynchronous storage backends
+- Components using the same key stay in sync; with the `localStorage` adapter, changes also propagate across browser tabs
+- Written in TypeScript — type definitions ship with the package
+- A single tiny runtime dependency: [`@plq/is`](https://www.npmjs.com/package/@plq/is)
+
+## Requirements
+
+To use `@plq/use-persisted-state`, you must use `react@16.8.0` or greater, which includes Hooks.
+The library is tested against React 19. The peer range allows React 16.8 and above, though only 19 is exercised in CI.
 
-## Example
+## Install
+
+```sh
+npm install @plq/use-persisted-state
+```
+
+## Quick start
 
 ```jsx
 import createPersistedState from '@plq/use-persisted-state'
-import storage from '@plq/use-persisted-state/lib/storages/local-storage'
+import storage from '@plq/use-persisted-state/storages/local-storage'
 
 const [usePersistedState] = createPersistedState('example', storage)
 
@@ -32,25 +48,64 @@ export default function App() {
 }
 ```
 
-[![Edit @plq/use-persisted-state](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/plquse-persisted-state-ob2od?fontsize=14)
+This example uses the bundled `localStorage` adapter; [Storage adapters](#storage-adapters) lists the rest and what each one is for.
+
+To try it locally, run the demo app from a repository checkout: `npm ci && npm run demo`.
+
+## API
+
+### `createPersistedState(name, storage)` — default export
+
+```ts
+const [usePersistedState, clear] = createPersistedState(name, storage)
+```
+
+- `name` — a namespace for this factory. All keys created by the returned hook are stored together in a single storage entry named `persisted_state_hook:<name>`.
+- `storage` — a synchronous or asynchronous storage backend implementing the [storage API](https://github.com/Akurganow/use-persisted-state/blob/main/docs/storage-api.md).
+
+Returns a `[usePersistedState, clear]` tuple. The default export detects whether the backend is asynchronous from the shape of its methods wherever it can — a `get` declared `async` settles the question without a call. Only when that does not hold does it call `get('')` once, as a method of your storage, to see whether the result is a `Promise`; `set` and `remove` are never invoked, so detection cannot write to your storage. All three members must be functions. If even a read during setup is undesirable, import one of the named factories below instead — they skip detection entirely.
+
+### Named factories
+
+```ts
+import { createPersistedState, createAsyncPersistedState } from '@plq/use-persisted-state'
+```
+
+- `createPersistedState(name, storage)` — for synchronous backends only (`localStorage`, `sessionStorage`).
+- `createAsyncPersistedState(name, storage)` — for asynchronous backends only (`browser.storage`, `chrome.storage`, custom promise-based backends).
+
+### `usePersistedState(key, initialValue)`
+
+```ts
+const [state, setState] = usePersistedState(key, initialValue)
+```
+
+Works like `useState`: returns the current state and a setter that accepts either a value or an updater function (`prev => next`). In addition, every update is written to the storage backend, and external changes to the stored value update the state.
+
+- Values are serialized with `JSON.stringify`, so they must be JSON-serializable (no functions, class instances, `Map`, `Set`, etc.). A few values serialize into something else rather than failing outright — see [Values JSON cannot carry](#values-json-cannot-carry).
+- With an asynchronous backend, the hook renders `initialValue` first and updates once the stored value has loaded.
+
+### `clear()`
 
-## Requirement
-To use `@plq/use-persisted-state`, you must use `react@16.8.0` or greater which includes Hooks.
-The library is fully compatible with React 18 and React 19.
+Removes the factory's whole storage entry. Hooks created by that factory fall back to their initial values. Returns `void` for synchronous backends and `Promise<void>` for asynchronous ones.
+
+### TypeScript
+
+The package ships its own type definitions. The storage contract and the hook's own types are exported from the entry point:
+
+```ts
+import type { Storage, AsyncStorage, StorageChange, StorageChangeListener } from '@plq/use-persisted-state'
+```
 
-## React 19 Compatibility
+`Storage` and `AsyncStorage` are the two backend contracts. `StorageChange`, `StorageChangeListener` and `StorageChangeEvent` describe the `onChanged` event an adapter provides. `PersistedState` and `UsePersistedState` type the hook and the tuple it returns.
 
-This library is fully compatible with React 19 and supports all new features:
-- Works seamlessly with `useTransition` for performance optimization
-- Compatible with `useActionState` for form handling
-- Supports `useOptimistic` for optimistic updates
+The longer `@plq/use-persisted-state/lib/@types/storage` path that earlier versions documented continues to work and resolves to the same types. Prefer the entry point: `lib/` is kept open for compatibility only.
 
-Check out our [React 19 examples](./demo/src/examples/) to see these features in action!
+## Clear storage
 
-## Clear Storage
 ```jsx
 import createPersistedState from '@plq/use-persisted-state'
-import storage from '@plq/use-persisted-state/lib/storages/local-storage'
+import storage from '@plq/use-persisted-state/storages/local-storage'
 
 const [usePersistedState, clear] = createPersistedState('example', storage)
 
@@ -67,44 +122,36 @@ export default function App() {
   )
 }
 ```
+
 ## Use sessionStorage
+
 ```jsx
 import createPersistedState from '@plq/use-persisted-state'
-import storage from '@plq/use-persisted-state/lib/storages/session-storage'
+import storage from '@plq/use-persisted-state/storages/session-storage'
 
 const [usePersistedState, clear] = createPersistedState('example', storage)
 ```
+
 ## Use async storage
+
 ```jsx
 import createPersistedState from '@plq/use-persisted-state'
-// or
+// or, to skip async detection:
 import { createAsyncPersistedState } from '@plq/use-persisted-state'
-import { local } from '@plq/use-persisted-state/lib/storages/browser-storage'
+import { local } from '@plq/use-persisted-state/storages/browser-storage'
 
 const [usePersistedState, clear] = createPersistedState('example', local)
 ```
+
 ## Use custom storage
 
-The [storage API](https://github.com/Akurganow/use-persisted-state/blob/master/docs/storage-api.md) is similar to the browser.storage but with a few differences
+The [storage API](https://github.com/Akurganow/use-persisted-state/blob/main/docs/storage-api.md) is similar to the WebExtensions `browser.storage` API, with a few differences. Any object implementing it works:
 
 ```jsx
 import createPersistedState from '@plq/use-persisted-state'
 
 const storageListeners = new Set()
 
-onChangeSomeStorage(event => {
-  const changes = {
-    [event.key]: {
-      newValue: event.newValue,
-      oldValue: event.oldValue,
-    },
-  }
-
-  listeners.forEach(listener => {
-    listener(changes)
-  })
-})
-
 const myStorage = {
   get: keys => getItemsFromSomeStorage(keys),
   set: items => setItemsToSomeStorage(items),
@@ -113,21 +160,103 @@ const myStorage = {
     addListener: listener => storageListeners.add(listener),
     removeListener: listener => storageListeners.delete(listener),
     hasListener: listener => storageListeners.has(listener),
-  }
+  },
 }
 
 const [usePersistedState, clear] = createPersistedState('example', myStorage)
 ```
+
+Your adapter owns that listener set and calls every listener when the backing store changes, which is what keeps components on the same key in sync. The [storage API](https://github.com/Akurganow/use-persisted-state/blob/main/docs/storage-api.md) documents the change payload and carries the complete example, including how to forward a backend's own events to the listeners.
+
 ## Storage adapters
-### [localStorage](https://developer.mozilla.org/docs/Web/API/Window/localStorage) `@plq/use-persisted-state/lib/storages/local-storage`
-  - Useful for average web application
-### [sessionStorage](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage) `@plq/use-persisted-state/lib/storages/session-storage`
-  - Useful for average web application
-### [browser.storage](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage) `@plq/use-persisted-state/lib/storages/browser-storage`
-  - Only for web extensions.
-  - Don't forget to set up [polyfill](https://github.com/mozilla/webextension-polyfill) if you want to run extension in Chrome browser.
-  - To use this storage you need to include the "storage" [permission](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in your `manifest.json` file
-### [chrome.storage](https://developer.chrome.com/apps/storage) `@plq/use-persisted-state/lib/storages/chrome-storage`
-  - Only for Chrome-based web extensions.
-  - If you develop extension that will be run only in Chrome browser you can use this storage without [polyfill](https://github.com/mozilla/webextension-polyfill).
-  - You must declare the "storage" permission in the [extension manifest](https://developer.chrome.com/apps/manifest) to use this storage.
+
+The longer `@plq/use-persisted-state/lib/storages/…` paths that earlier versions documented continue
+to work. Prefer the shorter ones below: imported from ES module code, the `lib` path hands back the
+CommonJS exports object rather than the adapter, so it needs an extra `.default` that the shorter
+path does not.
+
+### [localStorage](https://developer.mozilla.org/docs/Web/API/Window/localStorage) `@plq/use-persisted-state/storages/local-storage`
+
+- Useful for the average web application.
+- Synchronous. Changes made in other browser tabs are picked up through the [`storage` event](https://developer.mozilla.org/docs/Web/API/Window/storage_event).
+
+### [sessionStorage](https://developer.mozilla.org/docs/Web/API/Window/sessionStorage) `@plq/use-persisted-state/storages/session-storage`
+
+- Useful for state that should not outlive the browser session.
+- Synchronous.
+
+### [browser.storage](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage) `@plq/use-persisted-state/storages/browser-storage`
+
+- Only for web extensions. Asynchronous.
+- Named exports for each storage area: `local`, `sync` and `managed` (note that the [managed area](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/API/storage/managed) is read-only for the extension).
+- Don't forget to set up the [polyfill](https://github.com/mozilla/webextension-polyfill) if you want to run the extension in a Chromium-based browser.
+- You need to declare the "storage" [permission](https://developer.mozilla.org/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) in your `manifest.json` file.
+
+### [chrome.storage](https://developer.chrome.com/docs/extensions/reference/api/storage) `@plq/use-persisted-state/storages/chrome-storage`
+
+- Only for Chromium-based web extensions. Asynchronous.
+- Named exports for each storage area: `local`, `sync` and `managed` (the managed area is read-only for the extension).
+- If your extension runs only in Chromium-based browsers, you can use this adapter without the polyfill.
+- You must declare the "storage" permission in the [extension manifest](https://developer.chrome.com/docs/extensions/reference/manifest) to use this adapter.
+
+```jsx
+import createPersistedState from '@plq/use-persisted-state'
+import { local } from '@plq/use-persisted-state/storages/chrome-storage'
+
+const [usePersistedState, clear] = createPersistedState('example', local)
+```
+
+## Server-side rendering
+
+This library targets browser environments. Two things matter when rendering on a server:
+
+- The bundled `local-storage` and `session-storage` adapters can be imported without `localStorage` / `sessionStorage`. Where the global is missing the adapter reads back nothing and discards every write, so the hook keeps its initial value rather than throwing.
+- The synchronous hook reads from storage during render.
+
+When using an SSR framework (Next.js, Remix, etc.), make sure the components using the hook run only on the client — for example, in client-only components or behind a dynamic import that is disabled during SSR.
+
+## How values are stored
+
+Each factory keeps all of its keys in a single storage entry named `persisted_state_hook:<name>`, holding a JSON object with one property per key:
+
+```
+persisted_state_hook:example → {"count":0}
+```
+
+Storage backends only ever see serialized strings. Anything you persist ends up unencrypted in the underlying storage — do not store secrets or sensitive data (see [SECURITY.md](https://github.com/Akurganow/use-persisted-state/blob/main/SECURITY.md)).
+
+### An entry the library cannot read
+
+A write replaces the factory's whole entry, so there is nothing safe to store when the entry already
+there is a string that will not parse, or parses to something that is not an object — another
+library writing under the same key, or a write cut short. The setter reports the failure on
+`console.error`, keeps the value you set in memory and writes nothing, leaving every other hook's
+key exactly where it is. The factory's `clear` removes the entry and lets writing resume.
+
+This reaches as far as the adapter reports. Web storage holds only strings, so anything under the
+key comes back and is checked. Extension storage holds arbitrary JSON, and the bundled adapters
+report a non-string value as absent — the library then reads the entry as empty and its next write
+**replaces that value**. Storing your own data under a `persisted_state_hook:` key in extension
+storage is not safe, whatever its type.
+
+### Values JSON cannot carry
+
+A few values do not survive `JSON.stringify`. This follows from the format rather than from a choice
+the library makes, and no adapter can repair it: once a value has been written, nothing in storage
+tells a `null` you stored apart from a `null` that JSON produced.
+
+- **`undefined`** — the key is dropped, so nothing reaches storage at all. The component that set it
+  keeps `undefined` in memory, as `useState` would, and other components already mounted on that key
+  see no change and keep the value they hold. After a remount or a reload the key is absent, so the
+  initial value comes back.
+- **`NaN`, `Infinity`, `-Infinity`** — these are written as `null`. The component that set the value
+  keeps it until it remounts; every other component on that key reads back `null`, as does any
+  reader after a reload.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](https://github.com/Akurganow/use-persisted-state/blob/main/CONTRIBUTING.md) for setup, testing and the commit convention, and [CODE_OF_CONDUCT.md](https://github.com/Akurganow/use-persisted-state/blob/main/CODE_OF_CONDUCT.md) for community standards.
+
+## License
+
+[MIT](LICENSE)

package/esm/index.d.mts

@@ -0,0 +1,13 @@
+// Type-level aliases of the build output rather than restated signatures: a
+// copy keeps compiling after src changes and hands ESM consumers stale types
+// while CJS consumers get the current ones.
+export { default, createPersistedState, createAsyncPersistedState } from '../lib/index.js'
+export type {
+  AsyncStorage,
+  PersistedState,
+  Storage,
+  StorageChange,
+  StorageChangeEvent,
+  StorageChangeListener,
+  UsePersistedState,
+} from '../lib/index.js'

package/esm/index.mjs

@@ -0,0 +1,10 @@
+// Hand-written ES module wrapper over the single CJS build. A second compiled
+// ESM copy would duplicate the module-level listener registries, so hooks
+// loaded through one module system would stop seeing writes made through the
+// other. Values are re-exported through property access because Node's named
+// export detection for CJS is heuristic.
+import cjs from '../lib/index.js'
+
+export default cjs.default
+export const createPersistedState = cjs.createPersistedState
+export const createAsyncPersistedState = cjs.createAsyncPersistedState

package/esm/storages/browser-storage.d.mts

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

package/esm/storages/browser-storage.mjs

@@ -0,0 +1,5 @@
+import cjs from '../../lib/storages/browser-storage.js'
+
+export const local = cjs.local
+export const sync = cjs.sync
+export const managed = cjs.managed

package/esm/storages/chrome-storage.d.mts

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

package/esm/storages/chrome-storage.mjs

@@ -0,0 +1,5 @@
+import cjs from '../../lib/storages/chrome-storage.js'
+
+export const local = cjs.local
+export const sync = cjs.sync
+export const managed = cjs.managed

package/esm/storages/local-storage.d.mts

@@ -0,0 +1 @@
+export { default } from '../../lib/storages/local-storage.js'

package/esm/storages/local-storage.mjs

@@ -0,0 +1,3 @@
+import cjs from '../../lib/storages/local-storage.js'
+
+export default cjs.default

package/esm/storages/session-storage.d.mts

@@ -0,0 +1 @@
+export { default } from '../../lib/storages/session-storage.js'

package/esm/storages/session-storage.mjs

@@ -0,0 +1,3 @@
+import cjs from '../../lib/storages/session-storage.js'
+
+export default cjs.default

package/lib/@types/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/@types/storage.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,KAAK,IAAI,CAAA;AAEvF,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACnD,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtD,WAAW,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC;CACvD;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5D,GAAG,EAAE,CAAC,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAChD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;IAC1C,SAAS,EAAE,kBAAkB,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,GAAG,EAAE,CAAC,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,SAAS,EAAE,kBAAkB,CAAC;CAC/B"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/@types/storage.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,KAAK,IAAI,CAAA;AAEvF,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAClD,cAAc,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACrD,WAAW,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAA;CACtD;AAED,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAA;IAC3D,GAAG,EAAE,CAAC,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/C,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAA;IACzC,SAAS,EAAE,kBAAkB,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAA;IACpE,GAAG,EAAE,CAAC,KAAK,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,SAAS,EAAE,kBAAkB,CAAA;CAC9B"}

package/lib/create-async-persisted-state.d.ts

@@ -1,4 +1,4 @@
-import { AsyncStorage } from './@types/storage';
-import { PersistedState } from './@types/hook';
+import type { AsyncStorage } from './@types/storage';
+import type { PersistedState } from './@types/hook';
 export default function createAsyncPersistedState<S extends AsyncStorage>(storageKey: string, storage: S): [PersistedState, () => Promise<void>];
 //# sourceMappingURL=create-async-persisted-state.d.ts.map

package/lib/create-async-persisted-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-async-persisted-state.d.ts","sourceRoot":"","sources":["../src/create-async-persisted-state.ts"],"names":[],"mappings":"AAOA,OAAO,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAC,cAAc,EAAoB,MAAM,eAAe,CAAA;AAE/D,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,CAAC,SAAS,YAAY,EACtE,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,GACT,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAuCvC"}
+{"version":3,"file":"create-async-persisted-state.d.ts","sourceRoot":"","sources":["../src/create-async-persisted-state.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,eAAe,CAAA;AAEtE,MAAM,CAAC,OAAO,UAAU,yBAAyB,CAAC,CAAC,SAAS,YAAY,EACtE,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,CAAC,GACT,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA+IvC"}

package/lib/create-async-persisted-state.js

@@ -1,38 +1,157 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = createAsyncPersistedState;
 const react_1 = require("react");
-const use_storage_handler_1 = __importDefault(require("./utils/use-storage-handler"));
+const use_storage_handler_1 = __importStar(require("./utils/use-storage-handler"));
 const get_new_value_1 = __importDefault(require("./utils/get-new-value"));
 const get_new_item_1 = __importDefault(require("./utils/get-new-item"));
 const get_persisted_value_1 = __importDefault(require("./utils/get-persisted-value"));
 function createAsyncPersistedState(storageKey, storage) {
     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.resolve();
     const clear = () => {
-        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 usePersistedState = (key, initialValue) => {
-        const [state, setState] = (0, react_1.useState)(initialValue);
-        const setPersistedState = async (newState) => {
-            const newValue = (0, get_new_value_1.default)(newState, state);
-            setState(newValue);
+    const commitEntry = (key, newValue, pendingOwnWrites) => {
+        const write = entryWrites.then(async () => {
             const persistedItem = await storage.get(safeStorageKey);
-            const newItem = (0, get_new_item_1.default)(key, persistedItem[safeStorageKey], newValue);
+            let newItem;
+            try {
+                newItem = (0, get_new_item_1.default)(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.
+            (0, use_storage_handler_1.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 = (key, initialValue) => {
+        const [state, setState] = (0, react_1.useState)(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 = (0, react_1.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.
+        const hasAppliedValue = (0, react_1.useRef)(false);
+        const applyValue = (0, react_1.useCallback)((value) => {
+            latestValue.current = value;
+            hasAppliedValue.current = true;
+            setState(value);
+        }, []);
+        // The entries this hook has written and not yet seen reported back.
+        const pendingOwnWrites = (0, react_1.useRef)([]);
+        const setPersistedState = (0, react_1.useCallback)(async (newState) => {
+            const newValue = (0, get_new_value_1.default)(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(key, newValue, pendingOwnWrites);
+        }, [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 = (0, react_1.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.
+        (0, use_storage_handler_1.default)(key, safeStorageKey, applyValue, storage, initialValue, pendingOwnWrites);
         (0, react_1.useEffect)(() => {
-            const setInitialValue = async () => {
-                const persist = await storage.get(safeStorageKey);
-                const persistedState = persist[safeStorageKey];
-                const initialOrPersistedValue = (0, get_persisted_value_1.default)(key, initialValue, persistedState);
-                setState(initialOrPersistedValue);
+            // 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 () => {
+                try {
+                    const persist = await storage.get(safeStorageKey);
+                    if (isCancelled || hasAppliedValue.current)
+                        return;
+                    applyValue((0, get_persisted_value_1.default)(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);
+                }
+            };
+            loadPersistedValue();
+            return () => {
+                isCancelled = true;
             };
-            setInitialValue();
-        }, [initialValue, key]);
-        (0, use_storage_handler_1.default)(key, safeStorageKey, setState, storage, initialValue);
+        }, [key, applyValue]);
         return [state, setPersistedState];
     };
     return [usePersistedState, clear];

package/lib/create-async-persisted-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-async-persisted-state.js","sourceRoot":"","sources":["../src/create-async-persisted-state.ts"],"names":[],"mappings":";;;;;AAUA,4CA0CC;AApDD,iCAAgD;AAEhD,sFAA2D;AAC3D,0EAA+C;AAC/C,wEAA6C;AAC7C,sFAA2D;AAK3D,SAAwB,yBAAyB,CAC/C,UAAkB,EAClB,OAAU;IAEV,MAAM,cAAc,GAAG,wBAAwB,UAAU,EAAE,CAAA;IAE3D,MAAM,KAAK,GAAG,GAAkB,EAAE;QAChC,OAAO,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAA;IACvC,CAAC,CAAA;IAED,MAAM,iBAAiB,GAAG,CAAI,GAAW,EAAE,YAA2B,EAAwB,EAAE;QAC9F,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,IAAA,gBAAQ,EAAI,YAAY,CAAC,CAAA;QAEnD,MAAM,iBAAiB,GAAG,KAAK,EAAE,QAAiC,EAAiB,EAAE;YACnF,MAAM,QAAQ,GAAG,IAAA,uBAAW,EAAI,QAAQ,EAAE,KAAK,CAAC,CAAA;YAEhD,QAAQ,CAAC,QAAQ,CAAC,CAAA;YAElB,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;YACvD,MAAM,OAAO,GAAG,IAAA,sBAAU,EAAI,GAAG,EAAE,aAAa,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,CAAA;YAE3E,MAAM,OAAO,CAAC,GAAG,CAAC,EAAC,CAAC,cAAc,CAAC,EAAE,OAAO,EAAC,CAAC,CAAA;QAChD,CAAC,CAAA;QAED,IAAA,iBAAS,EAAC,GAAG,EAAE;YACb,MAAM,eAAe,GAAG,KAAK,IAAI,EAAE;gBACjC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;gBACjD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;gBAC9C,MAAM,uBAAuB,GAAG,IAAA,6BAAiB,EAAI,GAAG,EAAE,YAAY,EAAE,cAAc,CAAC,CAAA;gBAEvF,QAAQ,CAAC,uBAAuB,CAAC,CAAA;YACnC,CAAC,CAAA;YAED,eAAe,EAAE,CAAA;QACnB,CAAC,EAAE,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAA;QAEvB,IAAA,6BAAiB,EAAI,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CAAA;QAE1E,OAAO,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAA;IACnC,CAAC,CAAA;IAED,OAAO,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAA;AACnC,CAAC"}
+{"version":3,"file":"create-async-persisted-state.js","sourceRoot":"","sources":["../src/create-async-persisted-state.ts"],"names":[],"mappings":"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"}

package/lib/create-persisted-state.d.ts

@@ -1,4 +1,4 @@
-import { Storage } from './@types/storage';
-import { PersistedState } from './@types/hook';
+import type { Storage } from './@types/storage';
+import type { PersistedState } from './@types/hook';
 export default function createPersistedState(storageKey: string, storage: Storage): [PersistedState, () => void];
 //# sourceMappingURL=create-persisted-state.d.ts.map

package/lib/create-persisted-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-persisted-state.d.ts","sourceRoot":"","sources":["../src/create-persisted-state.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAA;AACxC,OAAO,EAAC,cAAc,EAAoB,MAAM,eAAe,CAAA;AAO/D,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC,CAoC9B"}
+{"version":3,"file":"create-persisted-state.d.ts","sourceRoot":"","sources":["../src/create-persisted-state.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,eAAe,CAAA;AAOtE,MAAM,CAAC,OAAO,UAAU,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC,CA0E/G"}