@choksheak/react-utils 0.2.7 → 0.2.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@choksheak/react-utils",
   "license": "The Unlicense",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Miscellaneous React+TypeScript utilities with support for full tree-shaking.",
   "private": false,
   "files": [
@@ -95,7 +95,7 @@
     "wretch": "^3.0.2"
   },
   "peerDependencies": {
-    "@choksheak/ts-utils": ">=0.2.9",
+    "@choksheak/ts-utils": ">=0.3.1",
     "lodash": ">=4.17.21",
     "object-sizeof": ">=2.6.5",
     "react": ">=16",
@@ -142,6 +142,45 @@
         "development": "./sharedState.cjs",
         "default": "./sharedState.cjs"
       }
+    },
+    "./storage": {
+      "types": "./storage.d.ts",
+      "import": {
+        "production": "./storage.min.mjs",
+        "development": "./storage.mjs",
+        "default": "./storage.mjs"
+      },
+      "require": {
+        "production": "./storage.min.cjs",
+        "development": "./storage.cjs",
+        "default": "./storage.cjs"
+      }
+    },
+    "./stringify": {
+      "types": "./stringify.d.ts",
+      "import": {
+        "production": "./stringify.min.mjs",
+        "development": "./stringify.mjs",
+        "default": "./stringify.mjs"
+      },
+      "require": {
+        "production": "./stringify.min.cjs",
+        "development": "./stringify.cjs",
+        "default": "./stringify.cjs"
+      }
+    },
+    "./useDeepMemo": {
+      "types": "./useDeepMemo.d.ts",
+      "import": {
+        "production": "./useDeepMemo.min.mjs",
+        "development": "./useDeepMemo.mjs",
+        "default": "./useDeepMemo.mjs"
+      },
+      "require": {
+        "production": "./useDeepMemo.min.cjs",
+        "development": "./useDeepMemo.cjs",
+        "default": "./useDeepMemo.cjs"
+      }
     }
   },
   "typesVersions": {
@@ -154,6 +193,15 @@
       ],
       "sharedState": [
         "./sharedState.d.ts"
+      ],
+      "storage": [
+        "./storage.d.ts"
+      ],
+      "stringify": [
+        "./stringify.d.ts"
+      ],
+      "useDeepMemo": [
+        "./useDeepMemo.d.ts"
       ]
     }
   }

package/sharedQuery.cjs

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var sharedQuery_exports = {};
 __export(sharedQuery_exports, {
   SharedQuery: () => SharedQuery,
-  SharedQueryDefaults: () => SharedQueryDefaults,
+  SharedQueryConfig: () => SharedQueryConfig,
+  configureSharedQuery: () => configureSharedQuery,
   sharedQuery: () => sharedQuery,
   useSharedQuery: () => useSharedQuery
 });
@@ -44,108 +45,48 @@ var import_react3 = require("react");
 var import_timeConstants = require("@choksheak/ts-utils/timeConstants");
 var import_react = require("react");
 
-// src/utils/storage.ts
+// src/storage.ts
 var import_kvStore = require("@choksheak/ts-utils/kvStore");
+var import_localStore = require("@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 import_localStore.LocalStore(store.key, {
+          defaultExpiryMs: expiryMs
+        }).asStorageAdapter();
+      case "indexedDb": {
+        const keyPrefix = store.key + ":";
+        return {
+          set: async (key, value) => {
+            await import_kvStore.kvStore.set(keyPrefix + key, value, expiryMs);
+          },
+          get: async (key) => {
+            return await import_kvStore.kvStore.get(keyPrefix + key);
+          },
+          delete: async (key) => {
+            await import_kvStore.kvStore.delete(keyPrefix + key);
+          },
+          clear: async () => {
+            await import_kvStore.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 import_kvStore.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 import_kvStore.kvStore.get(fullKey);
-    if (raw === void 0) return void 0;
-    try {
-      return JSON.parse(raw);
-    } catch {
-      await import_kvStore.kvStore.delete(fullKey);
-      return void 0;
-    }
-  }
-  async delete(key) {
-    if (typeof window === "undefined") return;
-    const fullKey = this.keyPrefix + ":" + key;
-    await import_kvStore.kvStore.delete(fullKey);
-  }
-  async clear() {
-    if (typeof window === "undefined") return;
-    await import_kvStore.kvStore.forEach(async (k) => {
-      if (k.startsWith(this.keyPrefix)) {
-        await import_kvStore.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.
@@ -212,12 +153,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();
     }
@@ -242,19 +185,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);
   }
 };
@@ -272,7 +215,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) => {
@@ -303,7 +246,7 @@ function stringifyDeterministicForKeys(params) {
   });
 }
 
-// src/utils/useDeepMemo.ts
+// src/useDeepMemo.ts
 var import_isEqual = __toESM(require("lodash/isEqual"));
 var import_react2 = require("react");
 function useDeepMemo(value) {
@@ -318,22 +261,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 * import_timeConstants2.MS_PER_DAY,
-  // 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;
@@ -350,32 +296,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. */
@@ -486,7 +432,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()) {
@@ -556,70 +509,64 @@ var SharedQuery = class {
       return;
     }
     const oldByteSize = (0, import_object_sizeof.default)(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 = (0, import_object_sizeof.default)(key) + (0, import_object_sizeof.default)(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 ? (0, import_object_sizeof.default)(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 = (0, import_object_sizeof.default)(key) + (0, import_object_sizeof.default)(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()} -> ${(0, import_object_sizeof.default)(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()} -> ${(0, import_object_sizeof.default)(newState).toLocaleString()}] (limit=${this.maxBytes.toLocaleString()})`
     );
   }
 };
@@ -635,7 +582,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 = (0, import_react3.useRef)(true);
@@ -643,23 +590,29 @@ function useSharedQuery(query, args = []) {
     () => query.getQueryKey(stableArgs),
     [query, stableArgs]
   );
-  const queryStateValue = queryState[queryKey];
+  const queryStateValue = queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;
   const setQueryStateValue = (0, import_react3.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] = (0, import_react3.useState)();
+  (0, import_react3.useEffect)(() => {
+    if (query.keepLastNonEmptyData && queryStateValue.data !== void 0) {
+      setLastNonEmptyData(queryStateValue.data);
+    }
+  }, [query.keepLastNonEmptyData, queryStateValue.data]);
   const execute = (0, import_react3.useCallback)(
     async (forceRefresh) => {
       query.log(`Begin executing shared query ${queryKey}`);
       setQueryStateValue((prev) => ({
         // Keep old data and error.
-        ...prev ?? {},
+        ...prev,
         lastUpdatedMs: Date.now(),
         loading: true
       }));
@@ -680,7 +633,7 @@ function useSharedQuery(query, args = []) {
           const now = Date.now();
           setQueryStateValue((prev) => ({
             // Keep old data.
-            ...prev ?? {},
+            ...prev,
             lastUpdatedMs: now,
             loading: false,
             error: e,
@@ -701,9 +654,9 @@ function useSharedQuery(query, args = []) {
     };
   }, [execute, query, queryKey]);
   return (0, import_react3.useMemo)(() => {
-    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.
@@ -718,7 +671,7 @@ function useSharedQuery(query, args = []) {
       setData: (data, dataUpdatedMs) => {
         const now = Date.now();
         setQueryStateValue((prev) => ({
-          ...prev ?? {},
+          ...prev,
           data,
           dataUpdatedMs: dataUpdatedMs ?? now,
           lastUpdatedMs: now,
@@ -735,6 +688,7 @@ function useSharedQuery(query, args = []) {
     };
   }, [
     execute,
+    lastNonEmptyData,
     query,
     queryKey,
     queryStateValue,
@@ -745,7 +699,8 @@ function useSharedQuery(query, args = []) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SharedQuery,
-  SharedQueryDefaults,
+  SharedQueryConfig,
+  configureSharedQuery,
   sharedQuery,
   useSharedQuery
 });