@choksheak/react-utils 0.2.5 → 0.2.7

package/README.md

@@ -2,4 +2,6 @@
 
 Miscellaneous React+TypeScript utilities with support for full tree-shaking.
 
+Source code: https://github.com/choksheak/react-utils
+
 Online docs: https://choksheak.github.io/react-utils/

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,12 +1,9 @@
 {
   "name": "@choksheak/react-utils",
   "license": "The Unlicense",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Miscellaneous React+TypeScript utilities with support for full tree-shaking.",
   "private": false,
-  "main": "index.js",
-  "module": "index.mjs",
-  "types": "index.d.ts",
   "files": [
     "**/*"
   ],
@@ -20,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

@@ -337,6 +337,12 @@ var SharedQueryDefaults = {
 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;
@@ -523,6 +529,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.
@@ -540,21 +559,29 @@ var SharedQuery = class {
     let newState = oldState;
     let needUpdate = false;
     if (this.maxSize) {
-      const numToCut = oldSize - 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;
-        Object.entries(newState).sort(
+        const entriesByTimeAscending = Object.entries(newState).sort(
           (entry1, entry2) => (
             // Sort descending.
-            entry2[1].lastUpdatedMs - entry1[1].lastUpdatedMs
+            entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
           )
-        ).slice(-numToCut).forEach(([key]) => {
-          delete newState[key];
-        });
+        );
+        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--;
+          }
+        }
       }
     }
     if (this.maxBytes && Object.keys(newState).length > 1) {
@@ -571,16 +598,16 @@ var SharedQuery = class {
         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++
-        ) {
+        for (let i = 0; i < entriesByTimeAscending.length && 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 (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;
+          }
         }
       }
     }
@@ -666,11 +693,13 @@ 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 {

package/sharedQuery.d.mts

@@ -1,7 +1,93 @@
 import { SharedStateOptions, SharedState } from './sharedState.mjs';
 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.
+ *
+ * Each shared query creates a new private shared state that handles the data
+ * storage. This shared state contains the records for all queries, where each
+ * query is a unique set of arguments used to make the query. The number of
+ * records and the total byte size of data can be limited so as to ensure the
+ * query does not take up too much memory.
+ *
+ * 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;
+/** An entry for a persisted state corresponding to one query key. */
 type QueryStateValue<TData> = {
     /**
      * When this record was last updated. Used for LRU determination. If you want
@@ -19,6 +105,7 @@ type QueryStateValue<TData> = {
     error?: unknown;
     errorUpdatedMs?: number;
 };
+/** Return type for useSharedQuery(). */
 type UseQueryResult<TData> = QueryStateValue<TData> & {
     /**
      * Cancels the inflight query (if any). Returns true if canceled.
@@ -35,12 +122,14 @@ 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> = {
     queryName: string;
     queryFn: QueryFn<TArgs, TData>;
@@ -62,9 +151,16 @@ declare const SharedQueryDefaults: {
     maxBytes: number;
     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;
@@ -132,6 +228,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.

package/sharedQuery.d.ts

@@ -1,5 +1,90 @@
+/**
+ * @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.
+ *
+ * Each shared query creates a new private shared state that handles the data
+ * storage. This shared state contains the records for all queries, where each
+ * query is a unique set of arguments used to make the query. The number of
+ * records and the total byte size of data can be limited so as to ensure the
+ * query does not take up too much memory.
+ *
+ * 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) : "-"}</>;
+ *   };
+ * ```
+ */
 import { SharedState, SharedStateOptions } from "./sharedState";
+/** Type of the queryFn used to fetch the data from source. */
 export type QueryFn<TArgs extends unknown[], TData> = (...args: TArgs) => Promise<TData> | TData;
+/** An entry for a persisted state corresponding to one query key. */
 export type QueryStateValue<TData> = {
     /**
      * When this record was last updated. Used for LRU determination. If you want
@@ -17,6 +102,7 @@ export type QueryStateValue<TData> = {
     error?: unknown;
     errorUpdatedMs?: number;
 };
+/** Return type for useSharedQuery(). */
 export type UseQueryResult<TData> = QueryStateValue<TData> & {
     /**
      * Cancels the inflight query (if any). Returns true if canceled.
@@ -33,12 +119,14 @@ export type UseQueryResult<TData> = QueryStateValue<TData> & {
     setData: (data: TData, dataUpdatedMs?: number) => void;
     deleteData: () => void;
 };
+/** List of all available persistence options. */
 export type PersistTo = "localStorage" | "indexedDb";
 /**
  * The full query state is a record of all the fetch states mapped by
  * query key to the state entry.
  */
 export type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;
+/** Options to configure a shared query. */
 export type SharedQueryOptions<TArgs extends unknown[], TData> = {
     queryName: string;
     queryFn: QueryFn<TArgs, TData>;
@@ -60,9 +148,16 @@ export declare const SharedQueryDefaults: {
     maxBytes: number;
     log: (...args: unknown[]) => void;
 };
+/** Please use sharedQuery() instead. */
 export 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;
@@ -130,6 +225,10 @@ export 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.

package/sharedQuery.min.cjs

@@ -1,2 +1,2 @@
-"use strict";var F=Object.create;var T=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var _=Object.getPrototypeOf,j=Object.prototype.hasOwnProperty;var J=(i,e)=>{for(var t in e)T(i,t,{get:e[t],enumerable:!0})},Q=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of R(e))!j.call(i,a)&&a!==t&&T(i,a,{get:()=>e[a],enumerable:!(r=L(e,a))||r.enumerable});return i};var K=(i,e,t)=>(t=i!=null?F(_(i)):{},Q(e||!i||!i.__esModule?T(t,"default",{value:i,enumerable:!0}):t,i)),W=i=>Q(T({},"__esModule",{value:!0}),i);var X={};J(X,{SharedQuery:()=>x,SharedQueryDefaults:()=>h,sharedQuery:()=>I,useSharedQuery:()=>H});module.exports=W(X);var q=require("@choksheak/ts-utils/timeConstants"),S=K(require("object-sizeof")),p=require("react");var B=require("@choksheak/ts-utils/timeConstants"),z=require("react");var f=require("@choksheak/ts-utils/kvStore");function k(i,e){let{localStorageKey:t,indexedDbKey:r,storeExpiryMs:a,store:s}=i??{};if(s)return s;let n=a||e;return t?new w(t,n):r?new D(r,n):null}var w=class{constructor(e,t){this.keyPrefix=e;this.expiryMs=t}save(e,t){if(typeof window>"u")return;let r=this.keyPrefix+":"+e;window.localStorage.setItem(r,JSON.stringify({value:t,expiresAt:this.expiryMs?Date.now()+this.expiryMs:0}))}load(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e,r=window.localStorage.getItem(t);if(r)try{let a=JSON.parse(r);if(!a||a.expiresAt&&Date.now()>=a.expiresAt){window.localStorage.removeItem(t);return}return a.value}catch{window.localStorage.removeItem(t);return}}delete(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e;window.localStorage.removeItem(t)}clear(){if(!(typeof window>"u"))for(let e of Object.keys(window.localStorage))e.startsWith(this.keyPrefix)&&window.localStorage.removeItem(e)}},D=class{constructor(e,t){this.keyPrefix=e;this.expiryMs=t}async save(e,t){if(typeof window>"u")return;let r=this.keyPrefix+":"+e;await f.kvStore.set(r,JSON.stringify(t),this.expiryMs)}async load(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e,r=await f.kvStore.get(t);if(r!==void 0)try{return JSON.parse(r)}catch{await f.kvStore.delete(t);return}}async delete(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e;await f.kvStore.delete(t)}async clear(){typeof window>"u"||await f.kvStore.forEach(async e=>{e.startsWith(this.keyPrefix)&&await f.kvStore.delete(e)})}};var O={storeExpiryMs:30*B.MS_PER_DAY,lazyLoad:!1},A=class{dataByKey=new Map;subscribersByKey=new Map;get(e){return this.dataByKey.get(e)}set(e,t){let r=this.dataByKey.get(e);r!==t&&(this.dataByKey.set(e,t),this.notify(e,t,r))}delete(e){this.dataByKey.delete(e)}setNoNotify(e,t){this.dataByKey.set(e,t)}subscribe(e,t){let r=this.subscribersByKey.get(e);return r||(r=new Set,this.subscribersByKey.set(e,r)),r.add(t),()=>{r.delete(t),r.size===0&&this.subscribersByKey.delete(e)}}notify(e,t,r){let a=this.subscribersByKey.get(e);if(!a)return;let s=Array.from(a.values());for(let n of s)try{n(t,r)}catch(l){console.error("Error invoking subscriber:",l)}}},g=new A,v="state",Y=0,M=class{constructor(e,t){this.defaultValue=e;this.pubSubKey=String(Y++),this.storageAdapter=k(t,O.storeExpiryMs),this.setValueBounded=s=>this.setValue(s),g.setNoNotify(this.pubSubKey,e);let r=t?.lazyLoad;(r!==void 0?r:O.lazyLoad)||this.initDefaultValueOnce()}pubSubKey;storageAdapter;setValueBounded;initDone=!1;subscribe(e){return g.subscribe(this.pubSubKey,()=>e())}getSnapshot(){return g.get(this.pubSubKey)}setValue(e){if(typeof e=="function"){let t=g.get(this.pubSubKey);e=e(t)}g.set(this.pubSubKey,e),this.storageAdapter?.save(v,e)}delete(){g.set(this.pubSubKey,this.defaultValue),this.storageAdapter?.save(v,this.defaultValue)}async initDefaultValueOnce(){if(this.initDone)return;this.initDone=!0;let e=await this.storageAdapter?.load(v);g.set(this.pubSubKey,e!==void 0?e:this.defaultValue)}};function V(i,e){return new M(i,e)}function P(i){return i.initDefaultValueOnce(),[(0,z.useSyncExternalStore)(t=>i.subscribe(t),()=>i.getSnapshot(),()=>i.getSnapshot()),i.setValueBounded]}function E(i){let e=new Set;return JSON.stringify(i,(t,r)=>{if(typeof r=="function")throw new Error("Functions should not be passed into query parameters");if(!r||typeof r!="object"||Array.isArray(r))return r;if(e.has(r))return"[Circular]";if(e.add(r),r!==i)try{JSON.stringify(r)}catch{return"[Unserializable]"}return Object.keys(r).sort().reduce((a,s)=>(a[s]=r[s],a),{})})}var $=K(require("lodash/isEqual")),m=require("react");function N(i){let[e,t]=(0,m.useState)(i);return(0,m.useMemo)(()=>e===i||(0,$.default)(e,i)?e:(t(i),i),[e,i])}var h={staleMs:0,expiryMs:30*q.MS_PER_DAY,refetchOnStale:!0,persistTo:void 0,maxSize:100,maxBytes:1e5,log:(...i)=>console.log("[sharedQuery]",...i)},x=class{inflightQueries=new Map;queryState;queryName;queryFn;expiryMs;staleMs;refetchOnStale;maxSize;maxBytes;log;constructor(e){if(this.queryName=e.queryName,this.queryFn=e.queryFn,this.staleMs=e?.staleMs??h.staleMs,this.expiryMs=e?.expiryMs??h.expiryMs,this.refetchOnStale=e?.refetchOnStale??h.refetchOnStale,!e.localStorageKey&&!e.indexedDbKey){let t=e.persistTo??h.persistTo;t==="localStorage"?e.localStorageKey=e.queryName:t==="indexedDb"&&(e.indexedDbKey=e.queryName)}this.maxSize=e?.maxSize??h.maxSize,this.maxBytes=e?.maxBytes??h.maxBytes,this.log=e?.log??h.log,this.queryState=V({},{...e,storeExpiryMs:e?.storeExpiryMs||this.expiryMs})}getQueryKey(e){return this.queryName+":"+E(e)}getAbortController(e){let t=this.getQueryKey(e);return this.getAbortControllerByKey(t)}getAbortControllerByKey(e){return this.inflightQueries.get(e)?.abortController??null}getAbortSignal(e){let t=this.getQueryKey(e);return this.getAbortSignalByKey(t)}getAbortSignalByKey(e){return this.getAbortControllerByKey(e)?.signal??null}isStale(e){return this.staleMs===0?!0:Date.now()-e>this.staleMs}isExpired(e){return this.expiryMs===0?!1:Date.now()-e>this.expiryMs}async getCachedOrFetch(...e){let t=this.getQueryKey(e),r=this.queryState.getSnapshot()?.[t];return r?.data&&!this.isExpired(r.dataUpdatedMs??0)?this.isStale(r.dataUpdatedMs??0)?(this.refetchOnStale&&(this.log(`refetchOnStale for ${t}`),this.dedupedFetch(t,...e)),this.log(`Returning stale data for ${t}`),r.data):(this.log(`Return fresh data ${t} from cache without fetching`),r.data):await this.dedupedFetch(t,...e)}dedupedFetch(e,...t){let r=this.inflightQueries.get(e);if(r)return this.log(`Deduplicating inflight fetch for ${e}`),r.promise;let a=this.startFetching(e,t),s=new AbortController;return this.inflightQueries.set(e,{promise:a,abortController:s}),a}async startFetching(e,t){this.log(`Start fetching ${e}`);try{let r=await this.queryFn(...t);return this.log(`Successfully fetched ${e}`),this.setData(e,r,Date.now()),r}catch(r){throw this.log(`Failed to fetch ${e}: ${r}`),r}finally{this.inflightQueries.delete(e)}}getQueryValue(e){return this.queryState.getSnapshot()?.[e]}getData(e){return this.queryState.getSnapshot()?.[e]?.data}setData(e,t,r=Date.now()){let a={lastUpdatedMs:Date.now(),loading:!1,data:t,dataUpdatedMs:r};this.queryState.setValue(s=>({...s,[e]:a})),this.enforceSizeLimit()}async updateFromSource(...e){let t=this.getQueryKey(e);return await this.dedupedFetch(t,...e)}deleteData(e){let r={...this.queryState.getSnapshot()};delete r[e],this.queryState.setValue(r);let a=this.inflightQueries.get(e);a&&(this.inflightQueries.delete(e),a.abortController.abort("Deleted"))}clear(){this.queryState.delete();for(let{abortController:e}of Array.from(this.inflightQueries.values()))e.abort("Cleared");this.inflightQueries.clear()}enforceSizeLimit(){if(!this.maxSize&&!this.maxBytes)return;let e=this.queryState.getSnapshot(),t=Object.keys(e).length;if(t<=1)return;let r=(0,S.default)(e),a=e,s=!1;if(this.maxSize){let n=t-this.maxSize;n>0&&(this.log(`enforceSizeLimit for ${this.queryName} needed due to size ${t} > ${this.maxSize}`),a={...a},s=!0,Object.entries(a).sort((l,c)=>c[1].lastUpdatedMs-l[1].lastUpdatedMs).slice(-n).forEach(([l])=>{delete a[l]}))}if(this.maxBytes&&Object.keys(a).length>1){let n=s?(0,S.default)(a):r,l=n-this.maxBytes;if(l>0){this.log(`enforceSizeLimit for ${this.queryName} needed due to byte size ${n.toLocaleString()} > ${this.maxBytes.toLocaleString()}`),s||(a={...a},s=!0);let c=Object.entries(a).sort((y,d)=>y[1].lastUpdatedMs-d[1].lastUpdatedMs);for(let y=0;y<c.length-1&&l>0;y++){let d=c[y][0],u=(0,S.default)(d)+(0,S.default)(a[d]);delete a[d],l-=u}}}if(s){this.queryState.setValue(a),this.log(`Trimmed data for ${this.queryName}: size=(${t} -> ${Object.keys(a).length}) (limit=${this.maxSize}), byteSize=(${r.toLocaleString()} -> ${(0,S.default)(a).toLocaleString()}) (limit=${this.maxBytes.toLocaleString()})`);return}this.log(`No need to trim data for ${this.queryName}: size=${t} (limit=${this.maxSize}), byteSize=${r.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`)}},U=new Set;function I(i){if(U.has(i.queryName))throw new Error(`Duplicate shared query "${i.queryName}"`);return U.add(i.queryName),new x(i)}var G={lastUpdatedMs:0,loading:!0};function H(i,e=[]){let t=N(e),[r,a]=P(i.queryState),s=(0,p.useRef)(!0),n=(0,p.useMemo)(()=>i.getQueryKey(t),[i,t]),l=r[n],c=(0,p.useCallback)(d=>{a(u=>{let o={...u};return o[n]=typeof d=="function"?d(o[n]):d,o})},[n,a]),y=(0,p.useCallback)(async d=>{i.log(`Begin executing shared query ${n}`),c(u=>({...u??{},lastUpdatedMs:Date.now(),loading:!0}));try{let u=await(d?i.updateFromSource(...t):i.getCachedOrFetch(...t));if(s.current){let o=Date.now();c({lastUpdatedMs:o,loading:!1,data:u,dataUpdatedMs:o})}}catch(u){if(s.current){let o=Date.now();c(b=>({...b??{},lastUpdatedMs:o,loading:!1,error:u,errorUpdatedMs:o}))}}},[i,n,c,t]);return(0,p.useEffect)(()=>(s.current=!0,y(!1),()=>{s.current=!1}),[y]),(0,p.useMemo)(()=>({...l??G,abortCurrentQuery:u=>{let o=i.getAbortControllerByKey(n);return o?.abort(u),!!o},refetch:()=>{y(!0)},setData:(u,o)=>{let b=Date.now();c(C=>({...C??{},data:u,dataUpdatedMs:o??b,lastUpdatedMs:b,loading:!1}))},deleteData:()=>{a(u=>{let o={...u};return delete o[n],o})}}),[y,i,n,l,a,c])}0&&(module.exports={SharedQuery,SharedQueryDefaults,sharedQuery,useSharedQuery});
+"use strict";var q=Object.create;var m=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var R=Object.getOwnPropertyNames;var _=Object.getPrototypeOf,j=Object.prototype.hasOwnProperty;var J=(i,e)=>{for(var t in e)m(i,t,{get:e[t],enumerable:!0})},K=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of R(e))!j.call(i,s)&&s!==t&&m(i,s,{get:()=>e[s],enumerable:!(r=L(e,s))||r.enumerable});return i};var Q=(i,e,t)=>(t=i!=null?q(_(i)):{},K(e||!i||!i.__esModule?m(t,"default",{value:i,enumerable:!0}):t,i)),W=i=>K(m({},"__esModule",{value:!0}),i);var X={};J(X,{SharedQuery:()=>x,SharedQueryDefaults:()=>h,sharedQuery:()=>I,useSharedQuery:()=>H});module.exports=W(X);var U=require("@choksheak/ts-utils/timeConstants"),S=Q(require("object-sizeof")),p=require("react");var O=require("@choksheak/ts-utils/timeConstants"),z=require("react");var f=require("@choksheak/ts-utils/kvStore");function k(i,e){let{localStorageKey:t,indexedDbKey:r,storeExpiryMs:s,store:a}=i??{};if(a)return a;let n=s||e;return t?new w(t,n):r?new D(r,n):null}var w=class{constructor(e,t){this.keyPrefix=e;this.expiryMs=t}save(e,t){if(typeof window>"u")return;let r=this.keyPrefix+":"+e;window.localStorage.setItem(r,JSON.stringify({value:t,expiresAt:this.expiryMs?Date.now()+this.expiryMs:0}))}load(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e,r=window.localStorage.getItem(t);if(r)try{let s=JSON.parse(r);if(!s||s.expiresAt&&Date.now()>=s.expiresAt){window.localStorage.removeItem(t);return}return s.value}catch{window.localStorage.removeItem(t);return}}delete(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e;window.localStorage.removeItem(t)}clear(){if(!(typeof window>"u"))for(let e of Object.keys(window.localStorage))e.startsWith(this.keyPrefix)&&window.localStorage.removeItem(e)}},D=class{constructor(e,t){this.keyPrefix=e;this.expiryMs=t}async save(e,t){if(typeof window>"u")return;let r=this.keyPrefix+":"+e;await f.kvStore.set(r,JSON.stringify(t),this.expiryMs)}async load(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e,r=await f.kvStore.get(t);if(r!==void 0)try{return JSON.parse(r)}catch{await f.kvStore.delete(t);return}}async delete(e){if(typeof window>"u")return;let t=this.keyPrefix+":"+e;await f.kvStore.delete(t)}async clear(){typeof window>"u"||await f.kvStore.forEach(async e=>{e.startsWith(this.keyPrefix)&&await f.kvStore.delete(e)})}};var B={storeExpiryMs:30*O.MS_PER_DAY,lazyLoad:!1},A=class{dataByKey=new Map;subscribersByKey=new Map;get(e){return this.dataByKey.get(e)}set(e,t){let r=this.dataByKey.get(e);r!==t&&(this.dataByKey.set(e,t),this.notify(e,t,r))}delete(e){this.dataByKey.delete(e)}setNoNotify(e,t){this.dataByKey.set(e,t)}subscribe(e,t){let r=this.subscribersByKey.get(e);return r||(r=new Set,this.subscribersByKey.set(e,r)),r.add(t),()=>{r.delete(t),r.size===0&&this.subscribersByKey.delete(e)}}notify(e,t,r){let s=this.subscribersByKey.get(e);if(!s)return;let a=Array.from(s.values());for(let n of a)try{n(t,r)}catch(y){console.error("Error invoking subscriber:",y)}}},g=new A,v="state",Y=0,M=class{constructor(e,t){this.defaultValue=e;this.pubSubKey=String(Y++),this.storageAdapter=k(t,B.storeExpiryMs),this.setValueBounded=a=>this.setValue(a),g.setNoNotify(this.pubSubKey,e);let r=t?.lazyLoad;(r!==void 0?r:B.lazyLoad)||this.initDefaultValueOnce()}pubSubKey;storageAdapter;setValueBounded;initDone=!1;subscribe(e){return g.subscribe(this.pubSubKey,()=>e())}getSnapshot(){return g.get(this.pubSubKey)}setValue(e){if(typeof e=="function"){let t=g.get(this.pubSubKey);e=e(t)}g.set(this.pubSubKey,e),this.storageAdapter?.save(v,e)}delete(){g.set(this.pubSubKey,this.defaultValue),this.storageAdapter?.save(v,this.defaultValue)}async initDefaultValueOnce(){if(this.initDone)return;this.initDone=!0;let e=await this.storageAdapter?.load(v);g.set(this.pubSubKey,e!==void 0?e:this.defaultValue)}};function V(i,e){return new M(i,e)}function $(i){return i.initDefaultValueOnce(),[(0,z.useSyncExternalStore)(t=>i.subscribe(t),()=>i.getSnapshot(),()=>i.getSnapshot()),i.setValueBounded]}function P(i){let e=new Set;return JSON.stringify(i,(t,r)=>{if(typeof r=="function")throw new Error("Functions should not be passed into query parameters");if(!r||typeof r!="object"||Array.isArray(r))return r;if(e.has(r))return"[Circular]";if(e.add(r),r!==i)try{JSON.stringify(r)}catch{return"[Unserializable]"}return Object.keys(r).sort().reduce((s,a)=>(s[a]=r[a],s),{})})}var C=Q(require("lodash/isEqual")),T=require("react");function E(i){let[e,t]=(0,T.useState)(i);return(0,T.useMemo)(()=>e===i||(0,C.default)(e,i)?e:(t(i),i),[e,i])}var h={staleMs:0,expiryMs:30*U.MS_PER_DAY,refetchOnStale:!0,persistTo:void 0,maxSize:100,maxBytes:1e5,log:(...i)=>console.log("[sharedQuery]",...i)},x=class{inflightQueries=new Map;queryState;mountedKeys=new Map;queryName;queryFn;expiryMs;staleMs;refetchOnStale;maxSize;maxBytes;log;constructor(e){if(this.queryName=e.queryName,this.queryFn=e.queryFn,this.staleMs=e?.staleMs??h.staleMs,this.expiryMs=e?.expiryMs??h.expiryMs,this.refetchOnStale=e?.refetchOnStale??h.refetchOnStale,!e.localStorageKey&&!e.indexedDbKey){let t=e.persistTo??h.persistTo;t==="localStorage"?e.localStorageKey=e.queryName:t==="indexedDb"&&(e.indexedDbKey=e.queryName)}this.maxSize=e?.maxSize??h.maxSize,this.maxBytes=e?.maxBytes??h.maxBytes,this.log=e?.log??h.log,this.queryState=V({},{...e,storeExpiryMs:e?.storeExpiryMs||this.expiryMs})}getQueryKey(e){return this.queryName+":"+P(e)}getAbortController(e){let t=this.getQueryKey(e);return this.getAbortControllerByKey(t)}getAbortControllerByKey(e){return this.inflightQueries.get(e)?.abortController??null}getAbortSignal(e){let t=this.getQueryKey(e);return this.getAbortSignalByKey(t)}getAbortSignalByKey(e){return this.getAbortControllerByKey(e)?.signal??null}isStale(e){return this.staleMs===0?!0:Date.now()-e>this.staleMs}isExpired(e){return this.expiryMs===0?!1:Date.now()-e>this.expiryMs}async getCachedOrFetch(...e){let t=this.getQueryKey(e),r=this.queryState.getSnapshot()?.[t];return r?.data&&!this.isExpired(r.dataUpdatedMs??0)?this.isStale(r.dataUpdatedMs??0)?(this.refetchOnStale&&(this.log(`refetchOnStale for ${t}`),this.dedupedFetch(t,...e)),this.log(`Returning stale data for ${t}`),r.data):(this.log(`Return fresh data ${t} from cache without fetching`),r.data):await this.dedupedFetch(t,...e)}dedupedFetch(e,...t){let r=this.inflightQueries.get(e);if(r)return this.log(`Deduplicating inflight fetch for ${e}`),r.promise;let s=this.startFetching(e,t),a=new AbortController;return this.inflightQueries.set(e,{promise:s,abortController:a}),s}async startFetching(e,t){this.log(`Start fetching ${e}`);try{let r=await this.queryFn(...t);return this.log(`Successfully fetched ${e}`),this.setData(e,r,Date.now()),r}catch(r){throw this.log(`Failed to fetch ${e}: ${r}`),r}finally{this.inflightQueries.delete(e)}}getQueryValue(e){return this.queryState.getSnapshot()?.[e]}getData(e){return this.queryState.getSnapshot()?.[e]?.data}setData(e,t,r=Date.now()){let s={lastUpdatedMs:Date.now(),loading:!1,data:t,dataUpdatedMs:r};this.queryState.setValue(a=>({...a,[e]:s})),this.enforceSizeLimit()}async updateFromSource(...e){let t=this.getQueryKey(e);return await this.dedupedFetch(t,...e)}deleteData(e){let r={...this.queryState.getSnapshot()};delete r[e],this.queryState.setValue(r);let s=this.inflightQueries.get(e);s&&(this.inflightQueries.delete(e),s.abortController.abort("Deleted"))}clear(){this.queryState.delete();for(let{abortController:e}of Array.from(this.inflightQueries.values()))e.abort("Cleared");this.inflightQueries.clear()}mount(e){this.mountedKeys.set(e,(this.mountedKeys.get(e)??0)+1)}unmount(e){let t=this.mountedKeys.get(e);t===1?this.mountedKeys.delete(e):this.mountedKeys.set(e,(t??0)-1)}enforceSizeLimit(){if(!this.maxSize&&!this.maxBytes)return;let e=this.queryState.getSnapshot(),t=Object.keys(e).length;if(t<=1)return;let r=(0,S.default)(e),s=e,a=!1;if(this.maxSize){let n=t-this.maxSize;if(n>0){this.log(`enforceSizeLimit for ${this.queryName} needed due to size ${t} > ${this.maxSize}`),s={...s},a=!0;let y=Object.entries(s).sort((l,o)=>l[1].lastUpdatedMs-o[1].lastUpdatedMs);for(let l=0;l<y.length&&n>0;l++){let o=y[l][0];this.mountedKeys.has(o)?this.log(`Cannot clean up ${o} as it is mounted`):(this.log(`Cleaning up unmounted ${o}`),delete s[o],n--)}}}if(this.maxBytes&&Object.keys(s).length>1){let n=a?(0,S.default)(s):r,y=n-this.maxBytes;if(y>0){this.log(`enforceSizeLimit for ${this.queryName} needed due to byte size ${n.toLocaleString()} > ${this.maxBytes.toLocaleString()}`),a||(s={...s},a=!0);let l=Object.entries(s).sort((o,d)=>o[1].lastUpdatedMs-d[1].lastUpdatedMs);for(let o=0;o<l.length&&y>0;o++){let d=l[o][0];if(this.mountedKeys.has(d))this.log(`Cannot clean up ${d} as it is mounted`);else{this.log(`Cleaning up unmounted ${d}`);let c=(0,S.default)(d)+(0,S.default)(s[d]);delete s[d],y-=c}}}}if(a){this.queryState.setValue(s),this.log(`Trimmed data for ${this.queryName}: size=(${t} -> ${Object.keys(s).length}) (limit=${this.maxSize}), byteSize=(${r.toLocaleString()} -> ${(0,S.default)(s).toLocaleString()}) (limit=${this.maxBytes.toLocaleString()})`);return}this.log(`No need to trim data for ${this.queryName}: size=${t} (limit=${this.maxSize}), byteSize=${r.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`)}},N=new Set;function I(i){if(N.has(i.queryName))throw new Error(`Duplicate shared query "${i.queryName}"`);return N.add(i.queryName),new x(i)}var G={lastUpdatedMs:0,loading:!0};function H(i,e=[]){let t=E(e),[r,s]=$(i.queryState),a=(0,p.useRef)(!0),n=(0,p.useMemo)(()=>i.getQueryKey(t),[i,t]),y=r[n],l=(0,p.useCallback)(d=>{s(c=>{let u={...c};return u[n]=typeof d=="function"?d(u[n]):d,u})},[n,s]),o=(0,p.useCallback)(async d=>{i.log(`Begin executing shared query ${n}`),l(c=>({...c??{},lastUpdatedMs:Date.now(),loading:!0}));try{let c=await(d?i.updateFromSource(...t):i.getCachedOrFetch(...t));if(a.current){let u=Date.now();l({lastUpdatedMs:u,loading:!1,data:c,dataUpdatedMs:u})}}catch(c){if(a.current){let u=Date.now();l(b=>({...b??{},lastUpdatedMs:u,loading:!1,error:c,errorUpdatedMs:u}))}}},[i,n,l,t]);return(0,p.useEffect)(()=>(a.current=!0,i.mount(n),o(!1),()=>{a.current=!1,i.unmount(n)}),[o,i,n]),(0,p.useMemo)(()=>({...y??G,abortCurrentQuery:c=>{let u=i.getAbortControllerByKey(n);return u?.abort(c),!!u},refetch:()=>{o(!0)},setData:(c,u)=>{let b=Date.now();l(F=>({...F??{},data:c,dataUpdatedMs:u??b,lastUpdatedMs:b,loading:!1}))},deleteData:()=>{s(c=>{let u={...c};return delete u[n],u})}}),[o,i,n,y,s,l])}0&&(module.exports={SharedQuery,SharedQueryDefaults,sharedQuery,useSharedQuery});
 //# sourceMappingURL=sharedQuery.min.cjs.map