@choksheak/react-utils 0.2.7 → 0.2.9

package/sharedQuery.mjs

@@ -1,114 +1,60 @@
 // src/sharedQuery.ts
 import { MS_PER_DAY as MS_PER_DAY2 } from "@choksheak/ts-utils/timeConstants";
 import getByteSize from "object-sizeof";
-import { useCallback, useEffect, useMemo as useMemo2, useRef } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo as useMemo2,
+  useRef,
+  useState as useState2
+} from "react";
 
 // src/sharedState.ts
 import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
 import { useSyncExternalStore } from "react";
 
-// src/utils/storage.ts
+// src/storage.ts
 import { kvStore } from "@choksheak/ts-utils/kvStore";
+import { LocalStore } from "@choksheak/ts-utils/localStore";
 function getStorageAdapter(options, defaultStoreExpiryMs) {
-  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
-  if (store) {
-    return store;
-  }
-  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
-  if (localStorageKey) {
-    return new LocalStorageAdapter(localStorageKey, expiryMs);
-  }
-  if (indexedDbKey) {
-    return new IndexedDbAdapter(indexedDbKey, expiryMs);
-  }
-  return null;
-}
-var LocalStorageAdapter = class {
-  constructor(keyPrefix, expiryMs) {
-    this.keyPrefix = keyPrefix;
-    this.expiryMs = expiryMs;
-  }
-  save(key, value) {
-    if (typeof window === "undefined") return;
-    const fullKey = this.keyPrefix + ":" + key;
-    window.localStorage.setItem(
-      fullKey,
-      JSON.stringify({
-        value,
-        expiresAt: this.expiryMs ? Date.now() + this.expiryMs : 0
-      })
-    );
-  }
-  load(key) {
-    if (typeof window === "undefined") return void 0;
-    const fullKey = this.keyPrefix + ":" + key;
-    const raw = window.localStorage.getItem(fullKey);
-    if (!raw) return void 0;
-    try {
-      const box = JSON.parse(raw);
-      if (!box || box.expiresAt && Date.now() >= box.expiresAt) {
-        window.localStorage.removeItem(fullKey);
-        return void 0;
-      }
-      return box.value;
-    } catch {
-      window.localStorage.removeItem(fullKey);
-      return void 0;
-    }
-  }
-  delete(key) {
-    if (typeof window === "undefined") return;
-    const fullKey = this.keyPrefix + ":" + key;
-    window.localStorage.removeItem(fullKey);
-  }
-  clear() {
-    if (typeof window === "undefined") return;
-    for (const key of Object.keys(window.localStorage)) {
-      if (key.startsWith(this.keyPrefix)) {
-        window.localStorage.removeItem(key);
+  const { store } = options ?? {};
+  if (!store) {
+    return null;
+  }
+  if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
+    const expiryMs = store.expiryMs || defaultStoreExpiryMs;
+    switch (store.persistTo) {
+      case "localStorage":
+        return new LocalStore(store.key, {
+          defaultExpiryMs: expiryMs
+        }).asStorageAdapter();
+      case "indexedDb": {
+        const keyPrefix = store.key + ":";
+        return {
+          set: async (key, value) => {
+            await kvStore.set(keyPrefix + key, value, expiryMs);
+          },
+          get: async (key) => {
+            return await kvStore.get(keyPrefix + key);
+          },
+          delete: async (key) => {
+            await kvStore.delete(keyPrefix + key);
+          },
+          clear: async () => {
+            await kvStore.clear();
+          }
+        };
       }
+      default:
+        store.persistTo;
+        throw new Error(`Unknown store.adapter ${store.persistTo}`);
     }
   }
-};
-var IndexedDbAdapter = class {
-  constructor(keyPrefix, expiryMs) {
-    this.keyPrefix = keyPrefix;
-    this.expiryMs = expiryMs;
-  }
-  async save(key, value) {
-    if (typeof window === "undefined") return;
-    const fullKey = this.keyPrefix + ":" + key;
-    await kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
-  }
-  async load(key) {
-    if (typeof window === "undefined") return void 0;
-    const fullKey = this.keyPrefix + ":" + key;
-    const raw = await kvStore.get(fullKey);
-    if (raw === void 0) return void 0;
-    try {
-      return JSON.parse(raw);
-    } catch {
-      await kvStore.delete(fullKey);
-      return void 0;
-    }
-  }
-  async delete(key) {
-    if (typeof window === "undefined") return;
-    const fullKey = this.keyPrefix + ":" + key;
-    await kvStore.delete(fullKey);
-  }
-  async clear() {
-    if (typeof window === "undefined") return;
-    await kvStore.forEach(async (k) => {
-      if (k.startsWith(this.keyPrefix)) {
-        await kvStore.delete(k);
-      }
-    });
-  }
-};
+  return store;
+}
 
 // src/sharedState.ts
-var SharedStateDefaults = {
+var SharedStateConfig = {
   /**
    * Default duration for storage expiration in milliseconds. Initial value
    * is 30 days, but can be changed to anything.
@@ -175,12 +121,14 @@ var SharedState = class {
     this.pubSubKey = String(stateKey++);
     this.storageAdapter = getStorageAdapter(
       options,
-      SharedStateDefaults.storeExpiryMs
+      SharedStateConfig.storeExpiryMs
     );
-    this.setValueBounded = (arg) => this.setValue(arg);
+    this.setValueBounded = (next) => {
+      this.setValue(next);
+    };
     pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
     const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateDefaults.lazyLoad;
+    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
     if (!lazy) {
       void this.initDefaultValueOnce();
     }
@@ -205,19 +153,19 @@ var SharedState = class {
       next = next(prev);
     }
     pubSubStore.set(this.pubSubKey, next);
-    void this.storageAdapter?.save(STORAGE_KEY, next);
+    void this.storageAdapter?.set(STORAGE_KEY, next);
   }
   // Remove the value of the shared state. Actually this just sets the value
   // back to the given default value.
   delete() {
     pubSubStore.set(this.pubSubKey, this.defaultValue);
-    void this.storageAdapter?.save(STORAGE_KEY, this.defaultValue);
+    void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);
   }
   // Initial default handling
   async initDefaultValueOnce() {
     if (this.initDone) return;
     this.initDone = true;
-    const v = await this.storageAdapter?.load(STORAGE_KEY);
+    const v = await this.storageAdapter?.get(STORAGE_KEY);
     pubSubStore.set(this.pubSubKey, v !== void 0 ? v : this.defaultValue);
   }
 };
@@ -235,7 +183,7 @@ function useSharedState(state) {
   return [value, state.setValueBounded];
 }
 
-// src/utils/stringify.ts
+// src/stringify.ts
 function stringifyDeterministicForKeys(params) {
   const cache = /* @__PURE__ */ new Set();
   return JSON.stringify(params, (_, value) => {
@@ -266,7 +214,7 @@ function stringifyDeterministicForKeys(params) {
   });
 }
 
-// src/utils/useDeepMemo.ts
+// src/useDeepMemo.ts
 import isEqual from "lodash/isEqual";
 import { useMemo, useState } from "react";
 function useDeepMemo(value) {
@@ -281,22 +229,25 @@ function useDeepMemo(value) {
 }
 
 // src/sharedQuery.ts
-var SharedQueryDefaults = {
-  // Refetch on every page load.
+var SharedQueryConfig = {
+  /** Refetch on every page load. */
   staleMs: 0,
-  // Keep in cache for a long time.
+  /** Keep in cache for a long time. */
   expiryMs: 30 * MS_PER_DAY2,
-  // Always refetch automatically if the data is stale.
+  /** Always refetch automatically if the data is stale. */
   refetchOnStale: true,
-  // No default persistence configured.
+  /** No default persistence configured. */
   persistTo: void 0,
-  // 100 is not too large, but please tweak accordingly.
+  /** 100 is not too large, but please tweak accordingly. */
   maxSize: 100,
-  // 100kb limit before discarding old records.
+  /** 100kb limit before discarding old records. */
   maxBytes: 1e5,
-  // Default to log to console.
+  /** Default to log to console. */
   log: (...args) => console.log("[sharedQuery]", ...args)
 };
+function configureSharedQuery(config) {
+  Object.assign(SharedQueryConfig, config);
+}
 var SharedQuery = class {
   inflightQueries = /* @__PURE__ */ new Map();
   queryState;
@@ -313,32 +264,32 @@ var SharedQuery = class {
   refetchOnStale;
   maxSize;
   maxBytes;
+  keepLastNonEmptyData;
   log;
   constructor(options) {
     this.queryName = options.queryName;
     this.queryFn = options.queryFn;
-    this.staleMs = options?.staleMs ?? SharedQueryDefaults.staleMs;
-    this.expiryMs = options?.expiryMs ?? SharedQueryDefaults.expiryMs;
-    this.refetchOnStale = options?.refetchOnStale ?? SharedQueryDefaults.refetchOnStale;
-    if (!options.localStorageKey && !options.indexedDbKey) {
-      const persistTo = options.persistTo ?? SharedQueryDefaults.persistTo;
-      if (persistTo === "localStorage") {
-        options.localStorageKey = options.queryName;
-      } else if (persistTo === "indexedDb") {
-        options.indexedDbKey = options.queryName;
+    this.staleMs = options?.staleMs ?? SharedQueryConfig.staleMs;
+    this.expiryMs = options?.expiryMs ?? SharedQueryConfig.expiryMs;
+    this.refetchOnStale = options?.refetchOnStale ?? SharedQueryConfig.refetchOnStale;
+    if (!options.store) {
+      const persistTo = options.persistTo ?? SharedQueryConfig.persistTo;
+      if (persistTo) {
+        options.store = {
+          persistTo,
+          key: options.queryName,
+          expiryMs: this.expiryMs
+        };
       }
     }
-    this.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
-    this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
-    this.log = options?.log ?? SharedQueryDefaults.log;
+    this.maxSize = options?.maxSize ?? SharedQueryConfig.maxSize;
+    this.maxBytes = options?.maxBytes ?? SharedQueryConfig.maxBytes;
+    this.keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);
+    this.log = options?.log ?? SharedQueryConfig.log;
     this.queryState = sharedState(
       {},
       // defaultValue
-      {
-        ...options,
-        // Fallback to use expiryMs for the storeExpiryMs.
-        storeExpiryMs: options?.storeExpiryMs || this.expiryMs
-      }
+      options
     );
   }
   /** Returns a key to identify requests based on the given args. */
@@ -449,7 +400,14 @@ var SharedQuery = class {
   }
   /** Get the current stored data for a query key. */
   getData(queryKey) {
-    return this.queryState.getSnapshot()?.[queryKey]?.data;
+    const stateValue = this.queryState.getSnapshot()?.[queryKey];
+    if (stateValue?.lastUpdatedMs) {
+      if (this.isExpired(stateValue.lastUpdatedMs)) {
+        this.deleteData(queryKey);
+        return void 0;
+      }
+    }
+    return stateValue?.data;
   }
   /** Set the data directly if the user obtained it from somewhere else. */
   setData(queryKey, data, dataUpdatedMs = Date.now()) {
@@ -519,70 +477,64 @@ var SharedQuery = class {
       return;
     }
     const oldByteSize = getByteSize(oldState);
-    let newState = oldState;
+    let numToCut = this.maxSize ? oldSize - this.maxSize : 0;
+    let bytesToCut = this.maxBytes ? oldByteSize - this.maxBytes : 0;
+    if (numToCut <= 0 && bytesToCut <= 0) {
+      this.log(
+        `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
+      );
+      return;
+    }
+    this.log(
+      `Need to trim ${this.queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`
+    );
+    const newState = { ...oldState };
     let needUpdate = false;
-    if (this.maxSize) {
-      let numToCut = oldSize - this.maxSize;
-      if (numToCut > 0) {
-        this.log(
-          `enforceSizeLimit for ${this.queryName} needed due to size ${oldSize} > ${this.maxSize}`
-        );
-        newState = { ...newState };
-        needUpdate = true;
-        const entriesByTimeAscending = Object.entries(newState).sort(
-          (entry1, entry2) => (
-            // Sort descending.
-            entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
-          )
-        );
-        for (let i = 0; i < entriesByTimeAscending.length && numToCut > 0; i++) {
-          const key = entriesByTimeAscending[i][0];
-          if (this.mountedKeys.has(key)) {
-            this.log(`Cannot clean up ${key} as it is mounted`);
-          } else {
-            this.log(`Cleaning up unmounted ${key}`);
-            delete newState[key];
-            numToCut--;
-          }
-        }
+    const deleteKeyIfNotMounted = (key, expired) => {
+      if (this.mountedKeys.has(key)) {
+        this.log(`Cannot clean up ${key} as it is mounted`);
+        return;
+      }
+      const byteSize = getByteSize(key) + getByteSize(newState[key]);
+      this.log(
+        `Cleaning up unmounted${expired ? ", expired" : ""} ${key} (byteSize=${byteSize.toLocaleString()})`
+      );
+      numToCut--;
+      bytesToCut -= byteSize;
+      delete newState[key];
+      needUpdate = true;
+    };
+    let entriesByTimeAscending = Object.entries(newState).sort(
+      (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+    );
+    for (const [key] of entriesByTimeAscending) {
+      if (!this.isExpired(newState[key].lastUpdatedMs)) {
+        break;
       }
+      deleteKeyIfNotMounted(key, true);
     }
-    if (this.maxBytes && Object.keys(newState).length > 1) {
-      const currentByteSize = needUpdate ? getByteSize(newState) : oldByteSize;
-      let bytesToCut = currentByteSize - this.maxBytes;
-      if (bytesToCut > 0) {
-        this.log(
-          `enforceSizeLimit for ${this.queryName} needed due to byte size ${currentByteSize.toLocaleString()} > ${this.maxBytes.toLocaleString()}`
-        );
-        if (!needUpdate) {
-          newState = { ...newState };
-          needUpdate = true;
-        }
-        const entriesByTimeAscending = Object.entries(newState).sort(
+    if (numToCut > 0 || bytesToCut > 0) {
+      if (needUpdate) {
+        entriesByTimeAscending = Object.entries(newState).sort(
           (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
         );
-        for (let i = 0; i < entriesByTimeAscending.length && bytesToCut > 0; i++) {
-          const key = entriesByTimeAscending[i][0];
-          if (this.mountedKeys.has(key)) {
-            this.log(`Cannot clean up ${key} as it is mounted`);
-          } else {
-            this.log(`Cleaning up unmounted ${key}`);
-            const thisSize = getByteSize(key) + getByteSize(newState[key]);
-            delete newState[key];
-            bytesToCut -= thisSize;
-          }
+      }
+      for (const [key] of entriesByTimeAscending) {
+        deleteKeyIfNotMounted(key, false);
+        if (numToCut <= 0 && bytesToCut <= 0) {
+          break;
         }
       }
     }
-    if (needUpdate) {
-      this.queryState.setValue(newState);
+    if (!needUpdate) {
       this.log(
-        `Trimmed data for ${this.queryName}: size=(${oldSize} -> ${Object.keys(newState).length}) (limit=${this.maxSize}), byteSize=(${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}) (limit=${this.maxBytes.toLocaleString()})`
+        `No trimmable entries found for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
       );
       return;
     }
+    this.queryState.setValue(newState);
     this.log(
-      `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
+      `Trimmed data for ${this.queryName}: size=[${oldSize} -> ${Object.keys(newState).length}] (limit=${this.maxSize}), byteSize=[${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}] (limit=${this.maxBytes.toLocaleString()})`
     );
   }
 };
@@ -598,7 +550,7 @@ var DEFAULT_QUERY_STATE_ENTRY = {
   lastUpdatedMs: 0,
   loading: true
 };
-function useSharedQuery(query, args = []) {
+function useSharedQuery(query, ...args) {
   const stableArgs = useDeepMemo(args);
   const [queryState, setQueryState] = useSharedState(query.queryState);
   const isMounted = useRef(true);
@@ -606,23 +558,29 @@ function useSharedQuery(query, args = []) {
     () => query.getQueryKey(stableArgs),
     [query, stableArgs]
   );
-  const queryStateValue = queryState[queryKey];
+  const queryStateValue = queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;
   const setQueryStateValue = useCallback(
-    (arg) => {
+    (next) => {
       setQueryState((prev) => {
         const clone = { ...prev };
-        clone[queryKey] = typeof arg === "function" ? arg(clone[queryKey]) : arg;
+        clone[queryKey] = typeof next === "function" ? next(clone[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY) : next;
         return clone;
       });
     },
     [queryKey, setQueryState]
   );
+  const [lastNonEmptyData, setLastNonEmptyData] = useState2();
+  useEffect(() => {
+    if (query.keepLastNonEmptyData && queryStateValue.data !== void 0) {
+      setLastNonEmptyData(queryStateValue.data);
+    }
+  }, [query.keepLastNonEmptyData, queryStateValue.data]);
   const execute = useCallback(
     async (forceRefresh) => {
       query.log(`Begin executing shared query ${queryKey}`);
       setQueryStateValue((prev) => ({
         // Keep old data and error.
-        ...prev ?? {},
+        ...prev,
         lastUpdatedMs: Date.now(),
         loading: true
       }));
@@ -643,7 +601,7 @@ function useSharedQuery(query, args = []) {
           const now = Date.now();
           setQueryStateValue((prev) => ({
             // Keep old data.
-            ...prev ?? {},
+            ...prev,
             lastUpdatedMs: now,
             loading: false,
             error: e,
@@ -664,9 +622,9 @@ function useSharedQuery(query, args = []) {
     };
   }, [execute, query, queryKey]);
   return useMemo2(() => {
-    const state = queryStateValue ?? DEFAULT_QUERY_STATE_ENTRY;
     return {
-      ...state,
+      ...queryStateValue,
+      lastNonEmptyData,
       // This works only if the user-given queryFn supports abort. If not,
       // this function doesn't do anything, since we don't have any means to
       // abort the running queryFn.
@@ -681,7 +639,7 @@ function useSharedQuery(query, args = []) {
       setData: (data, dataUpdatedMs) => {
         const now = Date.now();
         setQueryStateValue((prev) => ({
-          ...prev ?? {},
+          ...prev,
           data,
           dataUpdatedMs: dataUpdatedMs ?? now,
           lastUpdatedMs: now,
@@ -698,6 +656,7 @@ function useSharedQuery(query, args = []) {
     };
   }, [
     execute,
+    lastNonEmptyData,
     query,
     queryKey,
     queryStateValue,
@@ -707,7 +666,8 @@ function useSharedQuery(query, args = []) {
 }
 export {
   SharedQuery,
-  SharedQueryDefaults,
+  SharedQueryConfig,
+  configureSharedQuery,
   sharedQuery,
   useSharedQuery
 };