@plq/use-persisted-state 1.2.0 → 1.4.0

package/src/utils/use-storage-handler.ts

@@ -1,62 +1,138 @@
-import React, {useEffect} from 'react'
-import { AsyncStorage, Storage, StorageChange } from '../@types/storage'
-import { isFunction } from '@plq/is'
+import type React from 'react'
+import { useEffect, useRef } from 'react'
+import type { AsyncStorage, Storage, StorageChange } from '../@types/storage'
+import { isFunction, isObject } from '@plq/is'
 
-function getValue<T>(key: string, value: string) {
-  let newState = null
+/**
+ * One key read out of a serialized entry. `null` is a value a caller can store,
+ * so a stored `null` has to stay distinguishable from no value at all —
+ * collapsing the two is what dropped a persisted `null` on its way from a change
+ * event into state.
+ *
+ * A key that is not in the entry and an entry that will not parse are both
+ * `unavailable`. They differ in why, not in what a caller does next, and the
+ * difference that matters is reported where it happens: only a parse failure is
+ * a defect worth a diagnostic, an entry holding other keys is routine.
+ */
+type StoredValue<T> = { status: 'stored'; value: T } | { status: 'unavailable' }
+
+function readStoredValue<T>(key: string, entry: string): StoredValue<T> {
+  let parsed: unknown
 
   try {
-    newState = JSON.parse(value)
+    parsed = JSON.parse(entry)
   } catch (err) {
-    console.error('use-persisted-state: Can\'t parse value from storage', err)
+    console.error("use-persisted-state: Can't parse value from storage", err)
+
+    return { status: 'unavailable' }
   }
 
-  return newState && key in newState ? newState[key] as T : null
+  // A foreign entry can be any JSON value, and `in` throws on a primitive. This
+  // runs inside the adapter's notify loop, where a throw also cuts off every
+  // listener queued behind this one.
+  if (!isObject(parsed) || !(key in parsed)) return { status: 'unavailable' }
+
+  return { status: 'stored', value: parsed[key] as T }
 }
 
-function useStorageHandler<T>(
+// Restores the initial value when the whole entry is removed from the storage.
+function applyRemoval<T>(
+  change: StorageChange,
+  itemKey: string,
+  applyValue: (value: T) => void,
+  latestInitialValue: React.RefObject<T | (() => T)>,
+): void {
+  if (change.oldValue === null || change.oldValue === undefined) return
+
+  const oldValue = readStoredValue<T>(itemKey, change.oldValue)
+  const declaredInitialValue = latestInitialValue.current
+  // Compared against the resolved value: a factory is never equal to what it
+  // produces, so comparing the declaration re-applies the initial value on every
+  // removal.
+  const initialValue = isFunction(declaredInitialValue) ? declaredInitialValue() : declaredInitialValue
+
+  // An entry with no readable value for the key cannot be shown to have held the
+  // initial value, so the fallback is applied rather than skipped. The entry is
+  // gone either way, and stale state left in place is worse than a redundant
+  // restore.
+  if (oldValue.status === 'stored' && oldValue.value === initialValue) return
+
+  applyValue(initialValue)
+}
+
+/**
+ * Reports whether this change is the write the hook itself just made, forgetting
+ * the record when it is. A backend reports a write to every listener, the one
+ * that made it included, and applying that echo is the storage-to-state re-sync
+ * this hook was rebuilt without, arriving by another road: it decodes the entry
+ * again and hands the caller an equal value with a new identity, plus a render
+ * for a value it already holds.
+ *
+ * The price, accepted knowingly: for a value JSON cannot carry, the writer keeps
+ * what it set - NaN - while every other component on the key decodes the null
+ * that reached storage, so the two disagree until one of them remounts. Applying
+ * the echo would settle that disagreement and bring back both the second
+ * storage-to-state path and the render per write, so it is not the repair it
+ * looks like.
+ *
+ * Forgetting on the first match keeps a later identical entry a change. Another
+ * hook writing the same bytes is suppressed along with it, and nothing is lost:
+ * it would have replaced a value with an equal one.
+ */
+function consumeOwnWriteEcho(change: StorageChange, pendingOwnWrite: React.RefObject<string | null>): boolean {
+  if (pendingOwnWrite.current === null || change.newValue !== pendingOwnWrite.current) return false
+
+  pendingOwnWrite.current = null
+
+  return true
+}
+
+// Builds the change handler. Not a hook, despite living next to one.
+function createStorageHandler<T>(
   itemKey: string,
   storageKey: string,
-  setState: React.Dispatch<React.SetStateAction<T>>,
-  initialValue: T | (() => T),
+  applyValue: (value: T) => void,
+  latestInitialValue: React.RefObject<T | (() => T)>,
+  pendingOwnWrite: React.RefObject<string | null>,
 ) {
   return (changes: { [key: string]: StorageChange }): void => {
-    Object.entries(changes).forEach(([key, change]) => {
-      if (
-        key === storageKey
-        && (
-          change.newValue === null || change.newValue === undefined
-        )
-        && change.oldValue !== null
-        && change.oldValue !== undefined
-      ) {
-        const oldValue = getValue<T>(itemKey, change.oldValue)
-
-        if (oldValue !== initialValue) setState(isFunction(initialValue) ? initialValue() : initialValue)
-      }
+    for (const [key, change] of Object.entries(changes)) {
+      if (key !== storageKey) continue
 
-      if (
-        key === storageKey
-        && change.newValue !== null
-        && change.newValue !== undefined
-      ) {
-        const newValue = getValue<T>(itemKey, change.newValue)
+      if (consumeOwnWriteEcho(change, pendingOwnWrite)) continue
 
-        if (newValue !== null) setState(newValue)
+      if (change.newValue === null || change.newValue === undefined) {
+        applyRemoval<T>(change, itemKey, applyValue, latestInitialValue)
+        continue
       }
-    })
+
+      const newValue = readStoredValue<T>(itemKey, change.newValue)
+
+      if (newValue.status === 'stored') applyValue(newValue.value)
+    }
   }
 }
 
-export default function<T>(
+export default function useStorageHandler<T>(
   key: string,
   storageKey: string,
-  setState: React.Dispatch<React.SetStateAction<T>>,
+  applyValue: (value: T) => void,
   storage: AsyncStorage | Storage,
   initialValue: T | (() => T),
+  pendingOwnWrite: React.RefObject<string | null>,
 ): void {
+  // A removal restores the initial value the hook holds now, the same one the
+  // key-change path reads, so a caller whose default travels with its data gets
+  // that record's default back rather than the mounted one. Tracked through a ref
+  // rather than a dependency because an inline object or factory has a new
+  // identity every render, which would tear the subscription down and rebuild it;
+  // written during render, as the key the hook is rendering for is.
+  const latestInitialValue = useRef(initialValue)
+
+  latestInitialValue.current = initialValue
+
   useEffect(() => {
-    const handleStorage = useStorageHandler<T>(key, storageKey, setState, initialValue)
+    const handleStorage = createStorageHandler<T>(key, storageKey, applyValue, latestInitialValue, pendingOwnWrite)
 
     storage.onChanged.addListener(handleStorage)
 
@@ -65,5 +141,5 @@ export default function<T>(
         storage.onChanged.removeListener(handleStorage)
       }
     }
-  }, [initialValue, key, storage.onChanged, storageKey, setState])
+  }, [key, storage.onChanged, storageKey, applyValue, pendingOwnWrite])
 }

package/storages/browser-storage.d.ts

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

package/storages/browser-storage.js

@@ -0,0 +1,11 @@
+// Resolution stub for tooling that predates the exports map: TypeScript's
+// node10 resolver and older bundlers look for a real file at this path and
+// would otherwise fail. Node 16+ never reaches this file — the exports map
+// answers first. Each area is re-exported by reference, so both paths hand out
+// the same adapter instance and the listener registry stays single.
+const source = require('../lib/storages/browser-storage.js')
+
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.local = source.local
+exports.sync = source.sync
+exports.managed = source.managed

package/storages/chrome-storage.d.ts

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

package/storages/chrome-storage.js

@@ -0,0 +1,11 @@
+// Resolution stub for tooling that predates the exports map: TypeScript's
+// node10 resolver and older bundlers look for a real file at this path and
+// would otherwise fail. Node 16+ never reaches this file — the exports map
+// answers first. Each area is re-exported by reference, so both paths hand out
+// the same adapter instance and the listener registry stays single.
+const source = require('../lib/storages/chrome-storage.js')
+
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.local = source.local
+exports.sync = source.sync
+exports.managed = source.managed

package/storages/local-storage.d.ts

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

package/storages/local-storage.js

@@ -0,0 +1,9 @@
+// Resolution stub for tooling that predates the exports map: TypeScript's
+// node10 resolver and older bundlers look for a real file at this path and
+// would otherwise fail. Node 16+ never reaches this file — the exports map
+// answers first. The lib module's shape is mirrored rather than re-assigned to
+// module.exports, so the declaration beside it stays true for both resolvers.
+const source = require('../lib/storages/local-storage.js')
+
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.default = source.default

package/storages/session-storage.d.ts

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

package/storages/session-storage.js

@@ -0,0 +1,9 @@
+// Resolution stub for tooling that predates the exports map: TypeScript's
+// node10 resolver and older bundlers look for a real file at this path and
+// would otherwise fail. Node 16+ never reaches this file — the exports map
+// answers first. The lib module's shape is mirrored rather than re-assigned to
+// module.exports, so the declaration beside it stays true for both resolvers.
+const source = require('../lib/storages/session-storage.js')
+
+Object.defineProperty(exports, '__esModule', { value: true })
+exports.default = source.default

package/lib/utils/is-function.d.ts

@@ -1,2 +0,0 @@
-export default function isFunction(value: unknown): value is Function;
-//# sourceMappingURL=is-function.d.ts.map

package/lib/utils/is-function.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-function.d.ts","sourceRoot":"","sources":["../../src/utils/is-function.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAMpE"}

package/lib/utils/is-function.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-function isFunction(value) {
-    return !!value
-        && (Object.prototype.toString.call(value) === '[object Function]'
-            || typeof value === 'function');
-}
-exports.default = isFunction;
-//# sourceMappingURL=is-function.js.map

package/lib/utils/is-function.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-function.js","sourceRoot":"","sources":["../../src/utils/is-function.ts"],"names":[],"mappings":";;AAAA,SAAwB,UAAU,CAAC,KAAc;IAC/C,OAAO,CAAC,CAAC,KAAK;WACT,CACD,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,mBAAmB;eAC1D,OAAO,KAAK,KAAK,UAAU,CAC/B,CAAA;AACL,CAAC;AAND,6BAMC"}

package/lib/utils/is-promise.d.ts

@@ -1,2 +0,0 @@
-export default function isPromise<T = unknown>(value: unknown): value is PromiseLike<T>;
-//# sourceMappingURL=is-promise.d.ts.map

package/lib/utils/is-promise.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-promise.d.ts","sourceRoot":"","sources":["../../src/utils/is-promise.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAOtF"}

package/lib/utils/is-promise.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-function isPromise(value) {
-    return !!value
-        && (Object.prototype.toString.call(value) === '[object Promise]'
-            || typeof value === 'function')
-        && typeof value.then === 'function';
-}
-exports.default = isPromise;
-//# sourceMappingURL=is-promise.js.map

package/lib/utils/is-promise.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-promise.js","sourceRoot":"","sources":["../../src/utils/is-promise.ts"],"names":[],"mappings":";;AAAA,SAAwB,SAAS,CAAc,KAAc;IAC3D,OAAO,CAAC,CAAC,KAAK;WACT,CACD,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,kBAAkB;eACzD,OAAO,KAAK,KAAK,UAAU,CAC/B;WACE,OAAQ,KAA8B,CAAC,IAAI,KAAK,UAAU,CAAA;AACjE,CAAC;AAPD,4BAOC"}