@choksheak/react-utils 0.2.6 → 0.2.8

package/fetcher.cjs

@@ -31,21 +31,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var fetcher_exports = {};
 __export(fetcher_exports, {
   fetcher: () => fetcher,
-  fetcherWithRetries: () => fetcherWithRetries
+  simpleFetcher: () => simpleFetcher
 });
 module.exports = __toCommonJS(fetcher_exports);
 var import_wretch = __toESM(require("wretch"));
 var import_middlewares = require("wretch/middlewares");
-var fetcher = (0, import_wretch.default)();
-var fetcherWithRetries = (0, import_wretch.default)().middlewares([
+var fetcher = (0, import_wretch.default)().middlewares([
   (0, import_middlewares.retry)({
     maxAttempts: 3,
     delayTimer: 1e3,
     retryOnNetworkError: true
   })
 ]);
+var simpleFetcher = (0, import_wretch.default)();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   fetcher,
-  fetcherWithRetries
+  simpleFetcher
 });

package/fetcher.d.mts

@@ -1,8 +1,35 @@
 import * as wretch from 'wretch';
 
-/** Name this as "fetcher" to make it easier to understand. */
+/**
+ * @packageDocumentation
+ *
+ * An alternate syntax to fetch() that allows function chaining to compose the
+ * entire fetch request. One can also compose partial fetcher objects to be
+ * reused in future requests.
+ *
+ * Examples:
+ * ```
+ *   const userFetcher = fetcher
+ *     .auth("Bearer TOPSECRET")
+ *     .content("application/json")
+ *     .url("/api/user");
+ *
+ *   const user = await userFetcher.get();
+ *
+ *   const updateResult = await userFetcher
+ *     .body({ id: user.id, name: "New name"})
+ *     .post();
+ * ```
+ */
+/**
+ * Fetcher with default short retries. Use this to make your queries more
+ * robust without any additional work.
+ */
 declare const fetcher: wretch.Wretch<unknown, unknown, undefined, undefined>;
-/** Fetcher with default short retries. */
-declare const fetcherWithRetries: wretch.Wretch<unknown, unknown, undefined, undefined>;
+/**
+ * Name this as `simpleFetcher` to make it easier to understand than `wretch`.
+ * Use this if you don't want retries. Use `fetcher` if you want retries.
+ */
+declare const simpleFetcher: wretch.Wretch<unknown, unknown, undefined, undefined>;
 
-export { fetcher, fetcherWithRetries };
+export { fetcher, simpleFetcher };

package/fetcher.d.ts

@@ -1,4 +1,31 @@
-/** Name this as "fetcher" to make it easier to understand. */
+/**
+ * @packageDocumentation
+ *
+ * An alternate syntax to fetch() that allows function chaining to compose the
+ * entire fetch request. One can also compose partial fetcher objects to be
+ * reused in future requests.
+ *
+ * Examples:
+ * ```
+ *   const userFetcher = fetcher
+ *     .auth("Bearer TOPSECRET")
+ *     .content("application/json")
+ *     .url("/api/user");
+ *
+ *   const user = await userFetcher.get();
+ *
+ *   const updateResult = await userFetcher
+ *     .body({ id: user.id, name: "New name"})
+ *     .post();
+ * ```
+ */
+/**
+ * Fetcher with default short retries. Use this to make your queries more
+ * robust without any additional work.
+ */
 export declare const fetcher: import("wretch").Wretch<unknown, unknown, undefined, undefined>;
-/** Fetcher with default short retries. */
-export declare const fetcherWithRetries: import("wretch").Wretch<unknown, unknown, undefined, undefined>;
+/**
+ * Name this as `simpleFetcher` to make it easier to understand than `wretch`.
+ * Use this if you don't want retries. Use `fetcher` if you want retries.
+ */
+export declare const simpleFetcher: import("wretch").Wretch<unknown, unknown, undefined, undefined>;

package/fetcher.min.cjs

@@ -1,2 +1,2 @@
-"use strict";var f=Object.create;var m=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var d=Object.getPrototypeOf,n=Object.prototype.hasOwnProperty;var w=(r,e)=>{for(var t in e)m(r,t,{get:e[t],enumerable:!0})},p=(r,e,t,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of a(e))!n.call(r,o)&&o!==t&&m(r,o,{get:()=>e[o],enumerable:!(c=h(e,o))||c.enumerable});return r};var x=(r,e,t)=>(t=r!=null?f(d(r)):{},p(e||!r||!r.__esModule?m(t,"default",{value:r,enumerable:!0}):t,r)),y=r=>p(m({},"__esModule",{value:!0}),r);var u={};w(u,{fetcher:()=>l,fetcherWithRetries:()=>k});module.exports=y(u);var i=x(require("wretch")),s=require("wretch/middlewares"),l=(0,i.default)(),k=(0,i.default)().middlewares([(0,s.retry)({maxAttempts:3,delayTimer:1e3,retryOnNetworkError:!0})]);0&&(module.exports={fetcher,fetcherWithRetries});
+"use strict";var a=Object.create;var m=Object.defineProperty;var d=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var h=Object.getPrototypeOf,l=Object.prototype.hasOwnProperty;var n=(r,e)=>{for(var t in e)m(r,t,{get:e[t],enumerable:!0})},i=(r,e,t,c)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of f(e))!l.call(r,o)&&o!==t&&m(r,o,{get:()=>e[o],enumerable:!(c=d(e,o))||c.enumerable});return r};var w=(r,e,t)=>(t=r!=null?a(h(r)):{},i(e||!r||!r.__esModule?m(t,"default",{value:r,enumerable:!0}):t,r)),x=r=>i(m({},"__esModule",{value:!0}),r);var u={};n(u,{fetcher:()=>y,simpleFetcher:()=>k});module.exports=x(u);var p=w(require("wretch")),s=require("wretch/middlewares"),y=(0,p.default)().middlewares([(0,s.retry)({maxAttempts:3,delayTimer:1e3,retryOnNetworkError:!0})]),k=(0,p.default)();0&&(module.exports={fetcher,simpleFetcher});
 //# sourceMappingURL=fetcher.min.cjs.map

package/fetcher.min.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fetcher.ts"],"sourcesContent":["import wretch from \"wretch\";\nimport { retry } from \"wretch/middlewares\";\n\n/** Name this as \"fetcher\" to make it easier to understand. */\nexport const fetcher = wretch();\n\n/** Fetcher with default short retries. */\nexport const fetcherWithRetries = wretch().middlewares([\n  retry({\n    maxAttempts: 3,\n    delayTimer: 1000,\n    retryOnNetworkError: true,\n  }),\n]);\n"],"mappings":"0jBAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,aAAAE,EAAA,uBAAAC,IAAA,eAAAC,EAAAJ,GAAA,IAAAK,EAAmB,qBACnBC,EAAsB,8BAGTJ,KAAU,EAAAK,SAAO,EAGjBJ,KAAqB,EAAAI,SAAO,EAAE,YAAY,IACrD,SAAM,CACJ,YAAa,EACb,WAAY,IACZ,oBAAqB,EACvB,CAAC,CACH,CAAC","names":["fetcher_exports","__export","fetcher","fetcherWithRetries","__toCommonJS","import_wretch","import_middlewares","wretch"]}
+{"version":3,"sources":["../src/fetcher.ts"],"sourcesContent":["/**\n * @packageDocumentation\n *\n * An alternate syntax to fetch() that allows function chaining to compose the\n * entire fetch request. One can also compose partial fetcher objects to be\n * reused in future requests.\n *\n * Examples:\n * ```\n *   const userFetcher = fetcher\n *     .auth(\"Bearer TOPSECRET\")\n *     .content(\"application/json\")\n *     .url(\"/api/user\");\n *\n *   const user = await userFetcher.get();\n *\n *   const updateResult = await userFetcher\n *     .body({ id: user.id, name: \"New name\"})\n *     .post();\n * ```\n */\n\nimport wretch from \"wretch\";\nimport { retry } from \"wretch/middlewares\";\n\n/**\n * Fetcher with default short retries. Use this to make your queries more\n * robust without any additional work.\n */\nexport const fetcher = wretch().middlewares([\n  retry({\n    maxAttempts: 3,\n    delayTimer: 1000,\n    retryOnNetworkError: true,\n  }),\n]);\n\n/**\n * Name this as `simpleFetcher` to make it easier to understand than `wretch`.\n * Use this if you don't want retries. Use `fetcher` if you want retries.\n */\nexport const simpleFetcher = wretch();\n"],"mappings":"0jBAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,aAAAE,EAAA,kBAAAC,IAAA,eAAAC,EAAAJ,GAsBA,IAAAK,EAAmB,qBACnBC,EAAsB,8BAMTJ,KAAU,EAAAK,SAAO,EAAE,YAAY,IAC1C,SAAM,CACJ,YAAa,EACb,WAAY,IACZ,oBAAqB,EACvB,CAAC,CACH,CAAC,EAMYJ,KAAgB,EAAAI,SAAO","names":["fetcher_exports","__export","fetcher","simpleFetcher","__toCommonJS","import_wretch","import_middlewares","wretch"]}

package/fetcher.min.mjs

@@ -1,2 +1,2 @@
-import r from"wretch";import{retry as e}from"wretch/middlewares";var m=r(),i=r().middlewares([e({maxAttempts:3,delayTimer:1e3,retryOnNetworkError:!0})]);export{m as fetcher,i as fetcherWithRetries};
+import r from"wretch";import{retry as e}from"wretch/middlewares";var m=r().middlewares([e({maxAttempts:3,delayTimer:1e3,retryOnNetworkError:!0})]),p=r();export{m as fetcher,p as simpleFetcher};
 //# sourceMappingURL=fetcher.min.mjs.map

package/fetcher.min.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fetcher.ts"],"sourcesContent":["import wretch from \"wretch\";\nimport { retry } from \"wretch/middlewares\";\n\n/** Name this as \"fetcher\" to make it easier to understand. */\nexport const fetcher = wretch();\n\n/** Fetcher with default short retries. */\nexport const fetcherWithRetries = wretch().middlewares([\n  retry({\n    maxAttempts: 3,\n    delayTimer: 1000,\n    retryOnNetworkError: true,\n  }),\n]);\n"],"mappings":"AAAA,OAAOA,MAAY,SACnB,OAAS,SAAAC,MAAa,qBAGf,IAAMC,EAAUF,EAAO,EAGjBG,EAAqBH,EAAO,EAAE,YAAY,CACrDC,EAAM,CACJ,YAAa,EACb,WAAY,IACZ,oBAAqB,EACvB,CAAC,CACH,CAAC","names":["wretch","retry","fetcher","fetcherWithRetries"]}
+{"version":3,"sources":["../src/fetcher.ts"],"sourcesContent":["/**\n * @packageDocumentation\n *\n * An alternate syntax to fetch() that allows function chaining to compose the\n * entire fetch request. One can also compose partial fetcher objects to be\n * reused in future requests.\n *\n * Examples:\n * ```\n *   const userFetcher = fetcher\n *     .auth(\"Bearer TOPSECRET\")\n *     .content(\"application/json\")\n *     .url(\"/api/user\");\n *\n *   const user = await userFetcher.get();\n *\n *   const updateResult = await userFetcher\n *     .body({ id: user.id, name: \"New name\"})\n *     .post();\n * ```\n */\n\nimport wretch from \"wretch\";\nimport { retry } from \"wretch/middlewares\";\n\n/**\n * Fetcher with default short retries. Use this to make your queries more\n * robust without any additional work.\n */\nexport const fetcher = wretch().middlewares([\n  retry({\n    maxAttempts: 3,\n    delayTimer: 1000,\n    retryOnNetworkError: true,\n  }),\n]);\n\n/**\n * Name this as `simpleFetcher` to make it easier to understand than `wretch`.\n * Use this if you don't want retries. Use `fetcher` if you want retries.\n */\nexport const simpleFetcher = wretch();\n"],"mappings":"AAsBA,OAAOA,MAAY,SACnB,OAAS,SAAAC,MAAa,qBAMf,IAAMC,EAAUF,EAAO,EAAE,YAAY,CAC1CC,EAAM,CACJ,YAAa,EACb,WAAY,IACZ,oBAAqB,EACvB,CAAC,CACH,CAAC,EAMYE,EAAgBH,EAAO","names":["wretch","retry","fetcher","simpleFetcher"]}

package/fetcher.mjs

@@ -1,15 +1,15 @@
 // src/fetcher.ts
 import wretch from "wretch";
 import { retry } from "wretch/middlewares";
-var fetcher = wretch();
-var fetcherWithRetries = wretch().middlewares([
+var fetcher = wretch().middlewares([
   retry({
     maxAttempts: 3,
     delayTimer: 1e3,
     retryOnNetworkError: true
   })
 ]);
+var simpleFetcher = wretch();
 export {
   fetcher,
-  fetcherWithRetries
+  simpleFetcher
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@choksheak/react-utils",
   "license": "The Unlicense",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Miscellaneous React+TypeScript utilities with support for full tree-shaking.",
   "private": false,
   "files": [
@@ -17,6 +17,7 @@
     "test:watch": "vitest",
     "ci": "npm run lint && npm run tsc && npm run build && npm run test",
     "ls": "lint-staged",
+    "clean": "rm -rf dist",
     "docs": "rm -rf docs && typedoc `find src -name '*.ts' ! -name '*.test.ts'` --out docs --name 'Chok’s React Utilities'",
     "gen-types": "tsc --emitDeclarationOnly --declaration",
     "gen-exports": "tsx scripts/gen-exports.ts",

package/sharedQuery.cjs

@@ -214,7 +214,9 @@ var SharedState = class {
       options,
       SharedStateDefaults.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;
@@ -319,24 +321,30 @@ function useDeepMemo(value) {
 
 // src/sharedQuery.ts
 var SharedQueryDefaults = {
-  // Refetch on every page load.
+  /** 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)
 };
 var SharedQuery = class {
   inflightQueries = /* @__PURE__ */ new Map();
   queryState;
+  /**
+   * Keep track of the mounted query keys. This handles the case where an
+   * earlier-started query returns later, and when it returns, it was already
+   * unmounted, thus making it eligible for clean up right after fetch.
+   */
+  mountedKeys = /* @__PURE__ */ new Map();
   queryName;
   queryFn;
   expiryMs;
@@ -344,6 +352,7 @@ var SharedQuery = class {
   refetchOnStale;
   maxSize;
   maxBytes;
+  keepLastNonEmptyData;
   log;
   constructor(options) {
     this.queryName = options.queryName;
@@ -361,6 +370,7 @@ var SharedQuery = class {
     }
     this.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
     this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
+    this.keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);
     this.log = options?.log ?? SharedQueryDefaults.log;
     this.queryState = sharedState(
       {},
@@ -523,6 +533,19 @@ var SharedQuery = class {
     }
     this.inflightQueries.clear();
   }
+  /** Keep track of mounted keys. */
+  mount(queryKey) {
+    this.mountedKeys.set(queryKey, (this.mountedKeys.get(queryKey) ?? 0) + 1);
+  }
+  /** Clean up mounted keys. */
+  unmount(queryKey) {
+    const count = this.mountedKeys.get(queryKey);
+    if (count === 1) {
+      this.mountedKeys.delete(queryKey);
+    } else {
+      this.mountedKeys.set(queryKey, (count ?? 0) - 1);
+    }
+  }
   /**
    * Discard the oldest entries if the size exceeds the limit. The last
    * remaining record cannot be deleted no matter what the limit is.
@@ -537,62 +560,48 @@ 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) {
-      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];
-        });
+    const entriesByTimeAscending = Object.entries(newState).sort(
+      (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+    );
+    for (const [key] of entriesByTimeAscending) {
+      if (this.mountedKeys.has(key)) {
+        this.log(`Cannot clean up ${key} as it is mounted`);
+        continue;
       }
-    }
-    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;
-        }
+      const byteSize = (0, import_object_sizeof.default)(key) + (0, import_object_sizeof.default)(newState[key]);
+      this.log(
+        `Cleaning up unmounted ${key} (byteSize=${byteSize.toLocaleString()})`
+      );
+      numToCut--;
+      bytesToCut -= byteSize;
+      delete newState[key];
+      needUpdate = true;
+      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()})`
     );
   }
 };
@@ -616,23 +625,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
       }));
@@ -653,7 +668,7 @@ function useSharedQuery(query, args = []) {
           const now = Date.now();
           setQueryStateValue((prev) => ({
             // Keep old data.
-            ...prev ?? {},
+            ...prev,
             lastUpdatedMs: now,
             loading: false,
             error: e,
@@ -666,15 +681,17 @@ function useSharedQuery(query, args = []) {
   );
   (0, import_react3.useEffect)(() => {
     isMounted.current = true;
+    query.mount(queryKey);
     void execute(false);
     return () => {
       isMounted.current = false;
+      query.unmount(queryKey);
     };
-  }, [execute]);
+  }, [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.
@@ -689,7 +706,7 @@ function useSharedQuery(query, args = []) {
       setData: (data, dataUpdatedMs) => {
         const now = Date.now();
         setQueryStateValue((prev) => ({
-          ...prev ?? {},
+          ...prev,
           data,
           dataUpdatedMs: dataUpdatedMs ?? now,
           lastUpdatedMs: now,
@@ -706,6 +723,7 @@ function useSharedQuery(query, args = []) {
     };
   }, [
     execute,
+    lastNonEmptyData,
     query,
     queryKey,
     queryStateValue,

package/sharedQuery.d.mts

@@ -1,7 +1,10 @@
 import { SharedStateOptions, SharedState } from './sharedState.mjs';
+import 'react';
 import './utils/storage.mjs';
 
 /**
+ * @packageDocumentation
+ *
  * The "shared query" is a data fetching convenience library that helps users
  * to load data, check for staleness and expiration, cache in memory, local
  * storage or indexed db, and be able to manipulate the data anytime.
@@ -12,11 +15,81 @@ import './utils/storage.mjs';
  * records and the total byte size of data can be limited so as to ensure the
  * query does not take up too much memory.
  *
- * @packageDocumentation
+ * Example:
+ * ```
+ *   import { sharedQuery, useSharedQuery } from "@choksheak/react-utils/sharedQuery";
+ *
+ *   // Create a new shared query in the top level scope.
+ *   // The query function `queryFn` here does not take any arguments.
+ *   //
+ *   // Only the queryName and queryFn are required and everything else is
+ *   // optional.
+ *   //
+ *   // The queryName must be unique, otherwise we will throw an
+ *   // error. This is because defining the same queryName for two different
+ *   // queries implies that the queries are the same, thus violating the idea
+ *   // of a "shared" query, and almost certainly points to a bug in the code.
+ *   export const usersQuery = sharedQuery({
+ *     queryName: "users",
+ *     queryFn: listUsers,
+ *     persistTo: "indexedDb",
+ *     staleMs: MS_PER_DAY,
+ *   });
+ *
+ *   // Note that the query will only start fetching on mount in React.
+ *   // But you can do `usersQuery.getCachedOrFetch()` here to prefetch the
+ *   // data if necessary.
+ *   usersQuery.getCachedOrFetch();
+ *
+ *   // Example of using a query function with arguments.
+ *   export const getUserQuery = sharedQuery({
+ *     queryName: "getUser",
+ *     queryFn: getUser, // getUser(userId: string) => User
+ *     persistTo: "indexedDb",
+ *     staleMs: MS_PER_DAY,
+ *   });
+ *
+ *   export const UsersComponent: React.FC = () => {
+ *     // Second argument is optional, and is an array of arguments to be
+ *     // passed to the `queryFn`.
+ *     const users = useSharedQuery(usersQuery);
+ *
+ *     return (
+ *       <>
+ *         <h1>List of Users</h1>
+ *
+ *         <button onclick={users.refetch}>Refresh</button>
+ *
+ *         {users.loading && <Loader />}
+ *
+ *         {users.error && !users.data && <p>Error: {String(users.error)}</p>}
+ *
+ *         <p>Data: {users.data ? JSON.stringify(users.data) : "-"}</p>
+ *       </>
+ *     );
+ *   };
+ *
+ *   export const AnotherComponent: React.FC = () => {
+ *      // This query will be deduped with the one above, sharing the same
+ *      // data and the same fetches.
+ *      const users = useSharedQuery(usersQuery);
+ *      ...
+ *   };
+ *
+ *   export const DisplayOneUser: React.FC<{userId: string}> = ({userId}) => {
+ *      // Example of using the query with an argument. Whenever the argument
+ *      // changes, the data will be fetched and updated automatically.
+ *      const user = useSharedQuery(getUserQuery, [userId]);
+ *
+ *      return <>User: {user.data ? JSON.stringify(user.data) : "-"}</>;
+ *   };
+ * ```
  */
 
+/** Type of the queryFn used to fetch the data from source. */
 type QueryFn<TArgs extends unknown[], TData> = (...args: TArgs) => Promise<TData> | TData;
-type QueryStateValue<TData> = {
+/** An entry for a persisted state corresponding to one query key. */
+type QueryStateValue<TData> = Readonly<{
     /**
      * When this record was last updated. Used for LRU determination. If you want
      * the data age, please use `dataUpdatedMs` instead.
@@ -32,8 +105,14 @@ type QueryStateValue<TData> = {
      */
     error?: unknown;
     errorUpdatedMs?: number;
-};
-type UseQueryResult<TData> = QueryStateValue<TData> & {
+}>;
+/** Return type for useSharedQuery(). */
+type UseQueryResult<TData> = QueryStateValue<TData> & Readonly<{
+    /**
+     * Return the last non-empty data if you want to display the last loaded data
+     * while waiting for the new data to load.
+     */
+    lastNonEmptyData: TData | undefined;
     /**
      * Cancels the inflight query (if any). Returns true if canceled.
      */
@@ -48,37 +127,93 @@ type UseQueryResult<TData> = QueryStateValue<TData> & {
      */
     setData: (data: TData, dataUpdatedMs?: number) => void;
     deleteData: () => void;
-};
+}>;
+/** List of all available persistence options. */
 type PersistTo = "localStorage" | "indexedDb";
 /**
  * The full query state is a record of all the fetch states mapped by
  * query key to the state entry.
  */
 type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;
+/** Options to configure a shared query. */
 type SharedQueryOptions<TArgs extends unknown[], TData> = {
+    /**
+     * The name could have been auto-generated, but we let the user give us a
+     * human-readable name that can be identified quickly in the logs.
+     * Note that the queryKey is a string formed by the queryName plus the query
+     * arguments.
+     */
     queryName: string;
+    /**
+     * Function to fetch data.
+     */
     queryFn: QueryFn<TArgs, TData>;
+    /**
+     * ms before data considered stale; 0 means always stale.
+     */
     staleMs?: number;
+    /**
+     * ms before data is removed from cache; 0 means never expire.
+     */
     expiryMs?: number;
+    /**
+     * Trigger background re-fetch if stale.
+     */
     refetchOnStale?: boolean;
+    /**
+     * Shortcut to set the localStorageKey or indexedDbKey automatically from
+     * queryName. This is important because it avoids requiring the user to
+     * specify the same queryName twice everytime.
+     */
     persistTo?: PersistTo;
+    /**
+     * Max number of entries to keep. The oldest entries will be discarded.
+     * The last record cannot be discarded. 0 means no limit.
+     */
     maxSize?: number;
+    /**
+     * Max number of bytes to keep. The oldest entries will be discarded.
+     * The last record cannot be discarded. 0 means no limit.
+     */
     maxBytes?: number;
+    /**
+     * Keep a copy of the last non-empty data so that when you change the
+     * query arguments, you can still display the old data while waiting for the
+     * new data to load.
+     */
+    keepLastNonEmptyData?: boolean;
+    /**
+     * Customize the logger.
+     */
     log?: (...args: unknown[]) => void;
 } & SharedStateOptions<SharedQueryState<TData>>;
 /** Users can override these values globally. */
 declare const SharedQueryDefaults: {
+    /** Refetch on every page load. */
     staleMs: number;
+    /** Keep in cache for a long time. */
     expiryMs: number;
+    /** Always refetch automatically if the data is stale. */
     refetchOnStale: boolean;
+    /** No default persistence configured. */
     persistTo: PersistTo | undefined;
+    /** 100 is not too large, but please tweak accordingly. */
     maxSize: number;
+    /** 100kb limit before discarding old records. */
     maxBytes: number;
+    /** Default to log to console. */
     log: (...args: unknown[]) => void;
 };
+/** Please use sharedQuery() instead. */
 declare class SharedQuery<TArgs extends unknown[], TData> {
     private readonly inflightQueries;
     readonly queryState: SharedState<SharedQueryState<TData>>;
+    /**
+     * Keep track of the mounted query keys. This handles the case where an
+     * earlier-started query returns later, and when it returns, it was already
+     * unmounted, thus making it eligible for clean up right after fetch.
+     */
+    private readonly mountedKeys;
     readonly queryName: string;
     private readonly queryFn;
     readonly expiryMs: number;
@@ -86,6 +221,7 @@ declare class SharedQuery<TArgs extends unknown[], TData> {
     readonly refetchOnStale: boolean;
     readonly maxSize: number;
     readonly maxBytes: number;
+    readonly keepLastNonEmptyData: boolean;
     readonly log: (...args: unknown[]) => void;
     constructor(options: SharedQueryOptions<TArgs, TData>);
     /** Returns a key to identify requests based on the given args. */
@@ -146,6 +282,10 @@ declare class SharedQuery<TArgs extends unknown[], TData> {
     deleteData(queryKey: string): void;
     /** Delete all currently cached data & all inflight promises. */
     clear(): void;
+    /** Keep track of mounted keys. */
+    mount(queryKey: string): void;
+    /** Clean up mounted keys. */
+    unmount(queryKey: string): void;
     /**
      * Discard the oldest entries if the size exceeds the limit. The last
      * remaining record cannot be deleted no matter what the limit is.