@choksheak/react-utils 0.2.2 → 0.2.4

package/sharedQuery.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/sharedQuery.ts
@@ -27,7 +37,8 @@ __export(sharedQuery_exports, {
 });
 module.exports = __toCommonJS(sharedQuery_exports);
 var import_timeConstants2 = require("@choksheak/ts-utils/timeConstants");
-var import_react2 = require("react");
+var import_object_sizeof = __toESM(require("object-sizeof"));
+var import_react3 = require("react");
 
 // src/sharedState.ts
 var import_timeConstants = require("@choksheak/ts-utils/timeConstants");
@@ -292,34 +303,68 @@ function stringifyDeterministicForKeys(params) {
   });
 }
 
+// src/utils/useDeepMemo.ts
+var import_isEqual = __toESM(require("lodash/isEqual"));
+var import_react2 = require("react");
+function useDeepMemo(value) {
+  const [state, setState] = (0, import_react2.useState)(value);
+  return (0, import_react2.useMemo)(() => {
+    if (state === value || (0, import_isEqual.default)(state, value)) {
+      return state;
+    }
+    setState(value);
+    return value;
+  }, [state, value]);
+}
+
 // src/sharedQuery.ts
 var SharedQueryDefaults = {
+  // Refetch on every page load.
   staleMs: 0,
+  // Keep in cache for a long time.
   expiryMs: 30 * import_timeConstants2.MS_PER_DAY,
-  persistTo: void 0
+  // Always refetch automatically if the data is stale.
+  refetchOnStale: true,
+  // No default persistence configured.
+  persistTo: void 0,
+  // 100 is not too large, but please tweak accordingly.
+  maxSize: 100,
+  // 100kb limit before discarding old records.
+  maxBytes: 1e5,
+  // Default to log to console.
+  log: (...args) => console.log("[sharedQuery]", ...args)
 };
 var SharedQuery = class {
-  inflightPromises = /* @__PURE__ */ new Map();
+  inflightQueries = /* @__PURE__ */ new Map();
   queryState;
   queryName;
   queryFn;
   expiryMs;
   staleMs;
   refetchOnStale;
+  maxSize;
+  maxBytes;
+  log;
   constructor(options) {
     this.queryName = options.queryName;
     this.queryFn = options.queryFn;
-    this.expiryMs = options?.expiryMs !== void 0 ? options?.expiryMs : SharedQueryDefaults.expiryMs;
-    this.staleMs = options?.staleMs !== void 0 ? options?.staleMs : SharedQueryDefaults.staleMs;
-    this.refetchOnStale = Boolean(options?.refetchOnStale);
-    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 ?? 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.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
+    this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
+    this.log = options?.log ?? SharedQueryDefaults.log;
     this.queryState = sharedState(
       {},
+      // defaultValue
       {
         ...options,
         // Fallback to use expiryMs for the storeExpiryMs.
@@ -327,9 +372,24 @@ var SharedQuery = class {
       }
     );
   }
+  /** Returns a key to identify requests based on the given args. */
   getQueryKey(args) {
     return this.queryName + ":" + stringifyDeterministicForKeys(args);
   }
+  /**
+   * Get the AbortController to abort the inflight query (if any).
+   *
+   * Note that once you get the controller, you can also get the signal easily
+   * using `controller.signal`. So if you need both the controller and the
+   * signal, just use this function.
+   */
+  getAbortController(queryKey) {
+    return this.inflightQueries.get(queryKey)?.abortController ?? null;
+  }
+  /** Get the AbortSignal to check for query abortions. */
+  getAbortSignal(queryKey) {
+    return this.getAbortController(queryKey)?.signal ?? null;
+  }
   isStale(dataUpdatedMs) {
     if (this.staleMs === 0) return true;
     const ageMs = Date.now() - dataUpdatedMs;
@@ -345,52 +405,53 @@ var SharedQuery = class {
     const cached = this.queryState.getSnapshot()?.[queryKey];
     if (cached?.data && !this.isExpired(cached.dataUpdatedMs ?? 0)) {
       if (!this.isStale(cached.dataUpdatedMs ?? 0)) {
-        console.log(
-          `Return fresh data ${queryKey} from cache without fetching`
-        );
+        this.log(`Return fresh data ${queryKey} from cache without fetching`);
         return cached.data;
       }
       if (this.refetchOnStale) {
-        console.log(`refetchOnStale for ${queryKey}`);
+        this.log(`refetchOnStale for ${queryKey}`);
         void this.dedupedFetch(queryKey, ...args);
       }
-      console.log(`Returning stale data for ${queryKey}`);
+      this.log(`Returning stale data for ${queryKey}`);
       return cached.data;
     }
     return await this.dedupedFetch(queryKey, ...args);
   }
   dedupedFetch(queryKey, ...args) {
-    const inflightPromise = this.inflightPromises.get(queryKey);
-    if (inflightPromise) {
-      console.log(`Deduplicating inflight fetch for ${queryKey}`);
-      return inflightPromise;
+    const inflightQuery = this.inflightQueries.get(queryKey);
+    if (inflightQuery) {
+      this.log(`Deduplicating inflight fetch for ${queryKey}`);
+      return inflightQuery.promise;
     }
     const promise = this.startFetching(queryKey, args);
-    this.inflightPromises.set(queryKey, promise);
+    const abortController = new AbortController();
+    this.inflightQueries.set(queryKey, { promise, abortController });
     return promise;
   }
   async startFetching(queryKey, args) {
-    console.log(`Start fetching ${queryKey}`);
+    this.log(`Start fetching ${queryKey}`);
     try {
       const data = await this.queryFn(...args);
-      console.log(`Successfully fetched ${queryKey}`);
+      this.log(`Successfully fetched ${queryKey}`);
       this.setData(queryKey, data, Date.now());
       return data;
     } catch (e) {
-      console.error(`Failed to fetch ${queryKey}: ${e}`);
+      this.log(`Failed to fetch ${queryKey}: ${e}`);
       throw e;
     } finally {
-      this.inflightPromises.delete(queryKey);
+      this.inflightQueries.delete(queryKey);
     }
   }
   /** Set the data directly if the user obtained it from somewhere else. */
   async setData(queryKey, data, dataUpdatedMs = Date.now()) {
     const entry = {
+      lastUpdatedMs: Date.now(),
       loading: false,
       data,
       dataUpdatedMs
     };
     this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+    this.enforceSizeLimit();
   }
   /** Do a new fetch even when the data is already cached. */
   async updateFromSource(...args) {
@@ -398,18 +459,98 @@ var SharedQuery = class {
     return await this.dedupedFetch(key, ...args);
   }
   /** Delete the cached data for one set of arguments. */
-  deleteData(args) {
-    const queryKey = this.getQueryKey(args);
+  deleteData(queryKey) {
     const record = this.queryState.getSnapshot();
     const clone = { ...record };
     delete clone[queryKey];
     this.queryState.setValue(clone);
-    this.inflightPromises.delete(queryKey);
+    const inflight = this.inflightQueries.get(queryKey);
+    if (inflight) {
+      this.inflightQueries.delete(queryKey);
+      inflight.abortController.abort("Deleted");
+    }
   }
   /** Delete all currently cached data & all inflight promises. */
   clear() {
     this.queryState.delete();
-    this.inflightPromises.clear();
+    for (const { abortController } of Array.from(
+      this.inflightQueries.values()
+    )) {
+      abortController.abort("Cleared");
+    }
+    this.inflightQueries.clear();
+  }
+  /**
+   * Discard the oldest entries if the size exceeds the limit. The last
+   * remaining record cannot be deleted no matter what the limit is.
+   */
+  enforceSizeLimit() {
+    if (!this.maxSize && !this.maxBytes) {
+      return;
+    }
+    const oldState = this.queryState.getSnapshot();
+    const oldSize = Object.keys(oldState).length;
+    if (oldSize <= 1) {
+      return;
+    }
+    const oldByteSize = (0, import_object_sizeof.default)(oldState);
+    let newState = oldState;
+    let needUpdate = false;
+    if (this.maxSize) {
+      const numToCut = oldSize - this.maxSize;
+      if (numToCut > 0) {
+        this.log(
+          `enforceSizeLimit for ${this.queryName} needed due to size ${oldSize} > ${this.maxSize}`
+        );
+        newState = { ...newState };
+        needUpdate = true;
+        Object.entries(newState).sort(
+          (entry1, entry2) => (
+            // Sort descending.
+            entry2[1].lastUpdatedMs - entry1[1].lastUpdatedMs
+          )
+        ).slice(-numToCut).forEach(([key]) => {
+          delete newState[key];
+        });
+      }
+    }
+    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(
+          (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+        );
+        for (
+          let i = 0;
+          // Leave the last record entriesByTimeAscending[len-1] untouched.
+          i < entriesByTimeAscending.length - 1 && bytesToCut > 0;
+          i++
+        ) {
+          const key = entriesByTimeAscending[i][0];
+          const thisSize = (0, import_object_sizeof.default)(key) + (0, import_object_sizeof.default)(newState[key]);
+          delete newState[key];
+          bytesToCut -= thisSize;
+        }
+      }
+    }
+    if (needUpdate) {
+      this.queryState.setValue(newState);
+      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()})`
+      );
+      return;
+    }
+    this.log(
+      `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
+    );
   }
 };
 var seenQueryNames = /* @__PURE__ */ new Set();
@@ -420,74 +561,94 @@ function sharedQuery(options) {
   seenQueryNames.add(options.queryName);
   return new SharedQuery(options);
 }
-var DEFAULT_QUERY_STATE_ENTRY = { loading: true };
+var DEFAULT_QUERY_STATE_ENTRY = {
+  lastUpdatedMs: 0,
+  loading: true
+};
 function useSharedQuery(query, args = []) {
+  const stableArgs = useDeepMemo(args);
   const [queryState, setQueryState] = useSharedState(query.queryState);
-  const isMounted = (0, import_react2.useRef)(true);
-  const queryKey = query.getQueryKey(args);
-  const execute = (0, import_react2.useCallback)(async () => {
-    console.log(`Begin executing shared query ${queryKey}`);
-    setQueryState((prev) => {
-      const clone = { ...prev };
-      clone[queryKey] = {
-        ...clone[queryKey] ?? {},
-        loading: true
-      };
-      return clone;
-    });
-    try {
-      const data = await query.getCachedOrFetch(...args);
-      if (isMounted.current) {
-        setQueryState((prev) => {
-          const clone = { ...prev };
-          clone[queryKey] = {
-            // Don't keep old error.
-            loading: false,
-            data,
-            dataUpdatedMs: Date.now()
-          };
-          return clone;
-        });
-      }
-    } catch (e) {
-      const error = e instanceof Error ? e : new Error(`An unknown error occurred during fetch: ${e}`);
-      if (isMounted.current) {
-        setQueryState((prev) => {
-          const clone = { ...prev };
-          clone[queryKey] = {
-            // Keep old data.
-            ...clone[queryKey] ?? {},
-            loading: false,
-            error,
-            errorUpdatedMs: Date.now()
-          };
-          return clone;
-        });
+  const isMounted = (0, import_react3.useRef)(true);
+  const queryKey = (0, import_react3.useMemo)(
+    () => query.getQueryKey(stableArgs),
+    [query, stableArgs]
+  );
+  const queryStateValue = queryState[queryKey];
+  const execute = (0, import_react3.useCallback)(
+    async (forceRefresh) => {
+      query.log(`Begin executing shared query ${queryKey}`);
+      setQueryState((prev) => {
+        const clone = { ...prev };
+        clone[queryKey] = {
+          ...clone[queryKey] ?? {},
+          lastUpdatedMs: Date.now(),
+          loading: true
+        };
+        return clone;
+      });
+      try {
+        const data = await (forceRefresh ? query.updateFromSource(...stableArgs) : query.getCachedOrFetch(...stableArgs));
+        if (isMounted.current) {
+          setQueryState((prev) => {
+            const clone = { ...prev };
+            const now = Date.now();
+            clone[queryKey] = {
+              // Don't keep old error.
+              lastUpdatedMs: now,
+              loading: false,
+              data,
+              dataUpdatedMs: now
+            };
+            return clone;
+          });
+        }
+      } catch (e) {
+        if (isMounted.current) {
+          setQueryState((prev) => {
+            const clone = { ...prev };
+            const now = Date.now();
+            clone[queryKey] = {
+              // Keep old data.
+              ...clone[queryKey] ?? {},
+              lastUpdatedMs: now,
+              loading: false,
+              error: e,
+              errorUpdatedMs: now
+            };
+            return clone;
+          });
+        }
       }
-    }
-  }, [queryKey]);
-  (0, import_react2.useEffect)(() => {
+    },
+    [query, queryKey, setQueryState, stableArgs]
+  );
+  (0, import_react3.useEffect)(() => {
     isMounted.current = true;
-    void execute();
+    void execute(false);
     return () => {
       isMounted.current = false;
     };
   }, [execute]);
-  return (0, import_react2.useMemo)(() => {
-    const state = queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;
+  return (0, import_react3.useMemo)(() => {
+    const state = queryStateValue ?? DEFAULT_QUERY_STATE_ENTRY;
     return {
       ...state,
+      abortCurrentQuery: (reason) => {
+        const controller = query.getAbortController(queryKey);
+        controller?.abort(reason);
+        return Boolean(controller);
+      },
       refetch: () => {
-        return query.updateFromSource(...args);
+        void execute(true);
       },
       setData: (data, dataUpdatedMs) => {
         query.setData(queryKey, data, dataUpdatedMs ?? Date.now());
       },
       deleteData: () => {
-        query.deleteData(args);
+        query.deleteData(queryKey);
       }
     };
-  }, [query, queryKey, queryState]);
+  }, [execute, query, queryKey, queryStateValue]);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {