@choksheak/react-utils 0.4.4 → 0.4.5

package/index.mjs

@@ -1,29 +1,920 @@
+// src/sharedQuery.ts
+import { http, retries } from "@choksheak/ts-utils/http";
+import { nonNil } from "@choksheak/ts-utils/nonNil";
+import getByteSize from "object-sizeof";
 import {
-  SharedQueryConfig,
-  configureSharedQuery,
-  sharedQuery,
-  useSharedQuery
-} from "./chunk-FXCYHS3L.mjs";
-import {
-  SharedStateConfig,
-  configureSharedState,
-  sharedState,
-  useSharedState,
-  useSharedStateSetter,
-  useSharedStateValue
-} from "./chunk-YHU4KW2D.mjs";
-import {
-  getStorageAdapter,
-  kvStoreAdapter,
-  localStoreAdapter
-} from "./chunk-PHLY3LR4.mjs";
-import {
-  stringifyDeterministicForKeys
-} from "./chunk-4235I4VO.mjs";
-import {
-  useDeepMemo
-} from "./chunk-4J7TN5JN.mjs";
-import "./chunk-R7POPVJR.mjs";
+  useCallback,
+  useEffect,
+  useMemo as useMemo2,
+  useRef,
+  useState as useState2
+} from "react";
+import XXH from "xxhashjs";
+
+// src/sharedState.ts
+import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
+import { useSyncExternalStore } from "react";
+
+// src/storage.ts
+import { kvStore } from "@choksheak/ts-utils/kvStore";
+import { createLocalStore } from "@choksheak/ts-utils/localStore";
+var IS_NOT_BROWSER = typeof window === "undefined";
+function getStorageAdapter(options, defaultStoreExpiryMs) {
+  const { store } = options ?? {};
+  if (!store) {
+    return null;
+  }
+  if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
+    const expiryMs = store.expiryMs || defaultStoreExpiryMs;
+    const config = { ...store, expiryMs };
+    switch (store.persistTo) {
+      case "localStorage":
+        return localStoreAdapter(config);
+      case "indexedDb":
+        return kvStoreAdapter(config);
+      default:
+        store.persistTo;
+        throw new Error(`Unknown store.adapter ${store.persistTo}`);
+    }
+  }
+  return store;
+}
+function localStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const STORE_NAME = "react-utils";
+  const adapter = createLocalStore(STORE_NAME, {
+    defaultExpiryMs: expiryMs
+  });
+  const keyPrefix = key + ":";
+  return {
+    set: (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.set(keyPrefix + key2, value);
+    },
+    get: (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const fullKey = keyPrefix + key2;
+      const value = adapter.get(fullKey);
+      if (value !== void 0 && isValid && !isValid(value)) {
+        console.warn(
+          `localStorage adapter: Auto-discard invalid value for ${fullKey}: ${JSON.stringify(value)}`
+        );
+        adapter.delete(fullKey);
+        return void 0;
+      }
+      return value;
+    },
+    delete: (key2) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.delete(keyPrefix + key2);
+    },
+    /** Note that this will clear all keys in all shared states. */
+    clear: () => {
+      if (IS_NOT_BROWSER) return;
+      adapter.clear();
+    }
+  };
+}
+function kvStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const keyPrefix = key + ":";
+  return {
+    set: async (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.set(keyPrefix + key2, value, expiryMs);
+    },
+    get: async (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const fullKey = keyPrefix + key2;
+      const value = await kvStore.get(fullKey);
+      if (value !== void 0 && isValid && !isValid(value)) {
+        console.warn(
+          `indexedDb adapter: Auto-discard invalid value for ${key2}:`,
+          value
+        );
+        await kvStore.delete(fullKey);
+        return void 0;
+      }
+      return value;
+    },
+    delete: async (key2) => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.delete(keyPrefix + key2);
+    },
+    clear: async () => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.clear();
+    }
+  };
+}
+
+// src/sharedState.ts
+var SharedStateConfig = {
+  /**
+   * Default duration for storage expiration in milliseconds. Initial value
+   * is 30 days, but can be changed to anything.
+   */
+  storeExpiryMs: 30 * MS_PER_DAY,
+  /**
+   * True to load from storage only on mount, false (default) to load in
+   * the top level scope when the shared state is defined.
+   */
+  lazyLoad: false
+};
+function configureSharedState(config) {
+  Object.assign(SharedStateConfig, config);
+}
+function createPubSubStore() {
+  const dataByKey = /* @__PURE__ */ new Map();
+  const subscribersByKey = /* @__PURE__ */ new Map();
+  function notify(key, next, prev) {
+    const subscribers = subscribersByKey.get(key);
+    if (!subscribers) return;
+    const copy = Array.from(subscribers.values());
+    for (const subscriber of copy) {
+      try {
+        subscriber(next, prev);
+      } catch (e) {
+        console.error(`Error invoking subscriber:`, e);
+      }
+    }
+  }
+  return {
+    // This could be undefined if T includes undefined, else it should never
+    // return undefined because the user has to always specify the default value.
+    get(key) {
+      return dataByKey.get(key);
+    },
+    set(key, value) {
+      const prev = dataByKey.get(key);
+      if (prev === value) return;
+      dataByKey.set(key, value);
+      notify(key, value, prev);
+    },
+    delete(key) {
+      dataByKey.delete(key);
+    },
+    setNoNotify(key, value) {
+      dataByKey.set(key, value);
+    },
+    // Subscribe to changes of a specific key
+    subscribe(key, subscriber) {
+      let subscribers = subscribersByKey.get(key);
+      if (!subscribers) {
+        subscribers = /* @__PURE__ */ new Set();
+        subscribersByKey.set(key, subscribers);
+      }
+      subscribers.add(subscriber);
+      return () => {
+        subscribers.delete(subscriber);
+        if (subscribers.size === 0) subscribersByKey.delete(key);
+      };
+    }
+  };
+}
+function getOrCreatePubSubStore() {
+  if (typeof window !== "undefined") {
+    const t = window.globalThis;
+    return t.reactUtilsPubSubStore || (t.reactUtilsPubSubStore = createPubSubStore());
+  }
+  return createPubSubStore();
+}
+var pubSubStore = getOrCreatePubSubStore();
+var STORAGE_KEY = "state";
+var stateKey = 0;
+function sharedState(defaultValue, options) {
+  let readyResolve = () => {
+  };
+  const readyPromise = new Promise((resolve) => {
+    readyResolve = resolve;
+  });
+  const resolveReadyPromise = readyResolve;
+  const pubSubKey = String(stateKey++);
+  const storageAdapter = getStorageAdapter(
+    options,
+    SharedStateConfig.storeExpiryMs
+  );
+  pubSubStore.setNoNotify(pubSubKey, defaultValue);
+  const lazyLoad = options?.lazyLoad;
+  const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
+  function completeInit(stored) {
+    const value = stored !== void 0 ? stored : defaultValue;
+    pubSubStore.set(pubSubKey, value);
+    obj.initDone = true;
+    resolveReadyPromise();
+  }
+  const obj = {
+    defaultValue,
+    /** Allow users to await for the completion of data init. */
+    readyPromise,
+    lazy,
+    initStarted: false,
+    initDone: false,
+    /** `subscribe` function required by useSyncExternalStore. */
+    subscribe(subscriber) {
+      return pubSubStore.subscribe(pubSubKey, () => subscriber());
+    },
+    /** Returns true if there is a backing store. */
+    hasStore() {
+      return Boolean(storageAdapter);
+    },
+    /**
+     * Set a value directly into the store. Does nothing if there is no
+     * backing store.
+     *
+     * Warning: If you want to set the value properly, you should use
+     * `setValue()` instead which also updates the in-memory copy.
+     */
+    setInStore(value) {
+      return storageAdapter?.set(STORAGE_KEY, value);
+    },
+    /**
+     * Get a value directly from the store. Returns undefined if there is no
+     * backing store.
+     */
+    getFromStore() {
+      return storageAdapter?.get(STORAGE_KEY);
+    },
+    /**
+     * Get the value of the shared state.
+     *  `getSnapshot` function — must return same ref if value unchanged.
+     * Note that this would return the default value if data init from store is
+     * not completed yet.
+     */
+    getSnapshot() {
+      return pubSubStore.get(pubSubKey);
+    },
+    /** Set the value of the shared state. */
+    setValue(next) {
+      if (typeof next === "function") {
+        const prev = pubSubStore.get(pubSubKey);
+        next = next(prev);
+      }
+      pubSubStore.set(pubSubKey, next);
+      void obj.setInStore(next);
+    },
+    /**
+     * Remove the value of the shared state. Actually this just sets the value
+     * back to the given default value.
+     */
+    delete() {
+      pubSubStore.set(pubSubKey, defaultValue);
+      return storageAdapter?.set(STORAGE_KEY, defaultValue);
+    },
+    /** Initial default handling. */
+    initDefaultValueOnce() {
+      if (obj.initDone || obj.initStarted) return;
+      obj.initStarted = true;
+      const maybePromise = obj.getFromStore();
+      if (maybePromise instanceof Promise) {
+        return maybePromise.then(completeInit);
+      } else {
+        const stored = maybePromise;
+        completeInit(stored);
+      }
+    }
+  };
+  if (!lazy) {
+    obj.initDefaultValueOnce();
+  }
+  return obj;
+}
+function useSharedState(state) {
+  void state.initDefaultValueOnce();
+  const value = useSyncExternalStore(
+    (onStoreChange) => state.subscribe(onStoreChange),
+    () => state.getSnapshot(),
+    // getServerSnapshot is needed to prevent SSR dev errors in nextjs.
+    () => state.getSnapshot()
+  );
+  return [value, state.setValue];
+}
+function useSharedStateValue(state) {
+  return useSharedState(state)[0];
+}
+function useSharedStateSetter(state) {
+  void state.initDefaultValueOnce();
+  return state.setValue;
+}
+
+// src/stringify.ts
+function stringifyDeterministicForKeys(params) {
+  const cache = /* @__PURE__ */ new Set();
+  return JSON.stringify(params, (_, value) => {
+    if (typeof value === "function") {
+      throw new Error(`Functions should not be passed into query parameters`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return value;
+    }
+    if (cache.has(value)) {
+      return "[Circular]";
+    }
+    cache.add(value);
+    if (value !== params) {
+      try {
+        JSON.stringify(value);
+      } catch {
+        return "[Unserializable]";
+      }
+    }
+    return Object.keys(value).sort().reduce(
+      (result, key) => {
+        result[key] = value[key];
+        return result;
+      },
+      {}
+    );
+  });
+}
+
+// src/useDeepMemo.ts
+import { isEqual } from "lodash-es";
+import { useMemo, useState } from "react";
+function useDeepMemo(value) {
+  const [state, setState] = useState(value);
+  return useMemo(() => {
+    if (isEqual(state, value)) {
+      return state;
+    }
+    setState(value);
+    return value;
+  }, [state, value]);
+}
+
+// src/sharedQuery.ts
+var SharedQueryConfig = {
+  /** Refetch on every page load. */
+  staleMs: 0,
+  /** Keep in cache for a long time. */
+  expiryMs: 30 * 864e5,
+  /** 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)
+};
+function configureSharedQuery(config) {
+  Object.assign(SharedQueryConfig, config);
+}
+var moduleQueryRegistry = /* @__PURE__ */ new Map();
+function getOrCreateQueryRegistry() {
+  if (typeof window !== "undefined") {
+    const g = window.globalThis;
+    return g.reactUtilsQueryRegistry ??= /* @__PURE__ */ new Map();
+  }
+  return moduleQueryRegistry;
+}
+function sharedQuery1(options) {
+  const registry = getOrCreateQueryRegistry();
+  const key = options.queryName || options.url;
+  const existing = registry.get(
+    options.queryName || options.url
+  );
+  if (existing) {
+    return existing;
+  }
+  const obj = sharedQuery2(options);
+  registry.set(key, obj);
+  return obj;
+}
+function sharedQuery2(options) {
+  const url = options.url || "";
+  const queryName = options.queryName || url;
+  if (!queryName) {
+    throw new Error(`Either queryName or url must be specified.`);
+  }
+  const inflightQueries = /* @__PURE__ */ new Map();
+  const mountedKeys = /* @__PURE__ */ new Map();
+  let queryFn;
+  if (options.queryFn) {
+    queryFn = options.queryFn;
+  } else if (url) {
+    const fetcher = http.use(retries());
+    queryFn = async (...args) => {
+      let params = "";
+      const firstArg = args?.[0];
+      if (firstArg) {
+        if (typeof firstArg === "string") {
+          params = firstArg;
+        } else if (typeof firstArg === "object") {
+          const entries = [];
+          for (const [k, v] of Object.entries(firstArg)) {
+            if (v === void 0) continue;
+            if (Array.isArray(v)) {
+              for (const item of v) {
+                if (item === void 0) continue;
+                entries.push([k, String(item)]);
+              }
+            } else {
+              entries.push([k, String(v)]);
+            }
+          }
+          params = new URLSearchParams(entries).toString();
+        }
+        if (params) {
+          if (url.includes("?")) {
+            params = "&" + params;
+          } else {
+            params = "?" + params;
+          }
+        }
+      }
+      const response = await fetcher.get(url + params);
+      return await response.json();
+    };
+  } else {
+    throw new Error(`Either queryFn or url must be specified`);
+  }
+  const refetchFn = options.refetchFn;
+  const staleMs = options?.staleMs ?? SharedQueryConfig.staleMs;
+  const expiryMs = options?.expiryMs ?? SharedQueryConfig.expiryMs;
+  const refetchOnStale = options?.refetchOnStale ?? SharedQueryConfig.refetchOnStale;
+  const store = options.store;
+  if (store) {
+    if ("persistTo" in store && store.isValid) {
+      const isValid = store.isValid;
+      options = {
+        ...options,
+        store: {
+          ...store,
+          isValid: (u) => {
+            if (!u || typeof u !== "object") {
+              return false;
+            }
+            for (const v of Object.values(u)) {
+              if (!v || typeof v !== "object" || !("data" in v) || !("dataUpdatedMs" in v) || !("lastUpdatedMs" in v) || typeof v.dataUpdatedMs !== "number" || typeof v.lastUpdatedMs !== "number" || !isValid(v.data)) {
+                return false;
+              }
+            }
+            return true;
+          }
+        }
+      };
+    }
+  } else {
+    const persistTo = options.persistTo ?? SharedQueryConfig.persistTo;
+    if (persistTo) {
+      options = {
+        ...options,
+        store: {
+          persistTo,
+          key: queryName,
+          expiryMs
+        }
+      };
+    }
+  }
+  const maxSize = options?.maxSize ?? SharedQueryConfig.maxSize;
+  const maxBytes = options?.maxBytes ?? SharedQueryConfig.maxBytes;
+  const keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);
+  const log = options?.log ?? SharedQueryConfig.log;
+  const queryState = sharedState(
+    {},
+    // defaultValue
+    options
+  );
+  function isStale(dataUpdatedMs) {
+    if (staleMs === 0) return true;
+    const ageMs = Date.now() - dataUpdatedMs;
+    return ageMs > staleMs;
+  }
+  function isExpired(dataUpdatedMs) {
+    if (expiryMs === 0) return false;
+    const ageMs = Date.now() - dataUpdatedMs;
+    return ageMs > expiryMs;
+  }
+  function enforceSizeLimit() {
+    if (!maxSize && !maxBytes) {
+      return;
+    }
+    const oldState = queryState.getSnapshot();
+    const oldSize = Object.keys(oldState).length;
+    if (oldSize <= 1) {
+      return;
+    }
+    const oldByteSize = getByteSize(oldState);
+    let numToCut = maxSize ? oldSize - maxSize : 0;
+    let bytesToCut = maxBytes ? oldByteSize - maxBytes : 0;
+    if (numToCut <= 0 && bytesToCut <= 0) {
+      log(
+        `No need to trim data for ${queryName}: size=${oldSize} (limit=${maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${maxBytes.toLocaleString()})`
+      );
+      return;
+    }
+    log(
+      `Need to trim ${queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`
+    );
+    const newState = { ...oldState };
+    let needUpdate = false;
+    const deleteKeyIfNotMounted = (key, expired) => {
+      if (mountedKeys.has(key)) {
+        log(`Cannot clean up ${key} as it is mounted`);
+        return;
+      }
+      const byteSize = getByteSize(key) + getByteSize(newState[key]);
+      log(
+        `Cleaning up unmounted${expired ? ", expired" : ""} ${key} (byteSize=${byteSize.toLocaleString()})`
+      );
+      numToCut--;
+      bytesToCut -= byteSize;
+      delete newState[key];
+      needUpdate = true;
+    };
+    let entriesByTimeAscending = Object.entries(newState).sort(
+      (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+    );
+    for (const [key] of entriesByTimeAscending) {
+      if (!isExpired(newState[key].lastUpdatedMs)) {
+        break;
+      }
+      deleteKeyIfNotMounted(key, true);
+    }
+    if (numToCut > 0 || bytesToCut > 0) {
+      if (needUpdate) {
+        entriesByTimeAscending = Object.entries(newState).sort(
+          (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
+        );
+      }
+      for (const [key] of entriesByTimeAscending) {
+        deleteKeyIfNotMounted(key, false);
+        if (numToCut <= 0 && bytesToCut <= 0) {
+          break;
+        }
+      }
+    }
+    if (!needUpdate) {
+      log(
+        `No trimmable entries found for ${queryName}: size=${oldSize} (limit=${maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${maxBytes.toLocaleString()})`
+      );
+      return;
+    }
+    queryState.setValue(newState);
+    log(
+      `Trimmed data for ${queryName}: size=[${oldSize} -> ${Object.keys(newState).length}] (limit=${maxSize}), byteSize=[${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}] (limit=${maxBytes.toLocaleString()})`
+    );
+  }
+  function setData(queryKey, data, dataUpdatedMs = Date.now()) {
+    const entry = {
+      lastUpdatedMs: Date.now(),
+      loading: false,
+      data,
+      dataUpdatedMs
+    };
+    queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+    enforceSizeLimit();
+  }
+  async function startFetching(queryKey, queryType, args) {
+    log(`Start fetching ${queryKey}, queryType=${queryType}`);
+    try {
+      const data = await (queryType === "refetch" && refetchFn ? refetchFn(...args) : queryFn(...args));
+      log(`Successfully fetched ${queryKey}`);
+      setData(queryKey, data, Date.now());
+      return data;
+    } catch (e) {
+      log(`Failed to fetch ${queryKey} for queryType=${queryType}: ${e}`);
+      throw e;
+    } finally {
+      inflightQueries.delete(queryKey);
+    }
+  }
+  function dedupedFetch(queryKey, queryType, ...args) {
+    const inflightQuery = inflightQueries.get(queryKey);
+    if (inflightQuery) {
+      log(
+        `Deduplicating inflight fetch for ${queryKey}, queryType=${queryType}`
+      );
+      return inflightQuery.promise;
+    }
+    const promise = startFetching(queryKey, queryType, args);
+    const abortController = new AbortController();
+    inflightQueries.set(queryKey, { promise, abortController });
+    return promise;
+  }
+  const obj = {
+    queryName,
+    queryFn,
+    refetchFn,
+    expiryMs,
+    staleMs,
+    refetchOnStale,
+    maxSize,
+    maxBytes,
+    keepLastNonEmptyData,
+    log,
+    queryState,
+    /** Returns a key to identify requests based on the given args. */
+    getQueryKey(args) {
+      let s = stringifyDeterministicForKeys(args);
+      if (s.length > 30) {
+        s = XXH.h32(s, 39406).toString(16).slice(2);
+      }
+      return queryName + ":" + s;
+    },
+    /**
+     * 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(args) {
+      const queryKey = obj.getQueryKey(args);
+      return obj.getAbortControllerByKey(queryKey);
+    },
+    getAbortControllerByKey(queryKey) {
+      return inflightQueries.get(queryKey)?.abortController ?? null;
+    },
+    /**
+     * Get the AbortSignal to check for query abortions.
+     *
+     * Example using fetch:
+     * ```
+     *   const getUserQuery = sharedQuery({
+     *     queryName: "getUser",
+     *     queryFn: (userId: string) => {
+     *       // Get the signal for this current execution.
+     *       const signal = getUserQuery.getAbortSignal([userId]);
+     *
+     *       // Pass the signal to fetch so that it can be aborted.
+     *       const response = await fetch(`/users/${userId}`, { signal });
+     *
+     *       // Check for errors.
+     *       if (!response.ok) {
+     *         throw new Error(response.statusText);
+     *       }
+     *
+     *       // Return the data.
+     *       return await response.json();
+     *     },
+     *   });
+     * ```
+     *
+     * Example using `http.ts`:
+     * ```
+     *   const getUserQuery = sharedQuery({
+     *     queryName: "getUser",
+     *     queryFn: (userId: string) => {
+     *       // Get the signal for this current execution.
+     *       const signal = getUserQuery.getAbortSignal([userId]);
+     *
+     *       // Pass the signal to fetch so that it can be aborted.
+     *       const response = await http.get(`/users/${userId}`, { signal });
+     *       return await response.json();
+     *     },
+     *   });
+     * ```
+     */
+    getAbortSignal(args) {
+      const queryKey = obj.getQueryKey(args);
+      return obj.getAbortSignalByKey(queryKey);
+    },
+    getAbortSignalByKey(queryKey) {
+      return obj.getAbortControllerByKey(queryKey)?.signal ?? null;
+    },
+    /** For cached data, we need to return the correct timestamps as well. */
+    async getCachedOrFetch(...args) {
+      const startMs = Date.now();
+      await queryState.readyPromise;
+      const waitedMs = Date.now() - startMs;
+      const queryKey = obj.getQueryKey(args);
+      const cached = queryState.getSnapshot()?.[queryKey];
+      if (waitedMs) {
+        log(`${queryKey}: Waited for ${waitedMs}ms before data is ready`);
+      }
+      if (cached?.data && !isExpired(cached.dataUpdatedMs ?? 0)) {
+        if (!isStale(cached.dataUpdatedMs ?? 0)) {
+          log(`Return fresh data ${queryKey} from cache without fetching`);
+          return cached;
+        }
+        if (refetchOnStale) {
+          log(`refetchOnStale for ${queryKey}`);
+          void dedupedFetch(queryKey, "query", ...args);
+        }
+        log(`Returning stale data for ${queryKey}`);
+        return cached;
+      }
+      const data = await dedupedFetch(queryKey, "query", ...args);
+      const now = Date.now();
+      return {
+        // Don't keep old error.
+        lastUpdatedMs: now,
+        loading: false,
+        data,
+        dataUpdatedMs: now
+      };
+    },
+    /** Get the entire stored entry for a query key. */
+    getQueryValue(queryKey) {
+      return queryState.getSnapshot()?.[queryKey];
+    },
+    /** Get the current stored data for a query key. */
+    getData(queryKey) {
+      const stateValue = queryState.getSnapshot()?.[queryKey];
+      if (stateValue?.lastUpdatedMs) {
+        if (isExpired(stateValue.lastUpdatedMs)) {
+          obj.deleteData(queryKey);
+          return void 0;
+        }
+      }
+      return stateValue?.data;
+    },
+    /** Set the data directly if the user obtained it from somewhere else. */
+    setData,
+    /**
+     * Do a new fetch even when the data is already cached, but don't fetch if
+     * another fetch is already inflight.
+     */
+    async updateFromSource(...args) {
+      const key = obj.getQueryKey(args);
+      return await dedupedFetch(key, "query", ...args);
+    },
+    /**
+     * Perform an explicit refetch. If `options.refetchFn` was not specified,
+     * then this would be identical to calling `obj.updateFromSource()`.
+     */
+    async refetch(...args) {
+      const key = obj.getQueryKey(args);
+      return await dedupedFetch(key, "refetch", ...args);
+    },
+    /** Delete the cached data for one set of arguments. */
+    deleteData(queryKey) {
+      const record = queryState.getSnapshot();
+      const clone = { ...record };
+      delete clone[queryKey];
+      queryState.setValue(clone);
+      const inflight = inflightQueries.get(queryKey);
+      if (inflight) {
+        inflightQueries.delete(queryKey);
+        inflight.abortController.abort("Deleted");
+      }
+    },
+    /** Delete all currently cached data & all inflight promises. */
+    clear() {
+      queryState.delete();
+      for (const { abortController } of Array.from(inflightQueries.values())) {
+        abortController.abort("Cleared");
+      }
+      inflightQueries.clear();
+    },
+    /** Keep track of mounted keys. */
+    mount(queryKey) {
+      mountedKeys.set(queryKey, (mountedKeys.get(queryKey) ?? 0) + 1);
+    },
+    /** Clean up mounted keys. */
+    unmount(queryKey) {
+      const count = mountedKeys.get(queryKey);
+      if (count === 1) {
+        mountedKeys.delete(queryKey);
+      } else {
+        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.
+     */
+    enforceSizeLimit
+  };
+  return obj;
+}
+function sharedQuery(options) {
+  return sharedQuery1(options);
+}
+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 = useRef(true);
+  const queryKey = useMemo2(
+    () => query.getQueryKey(stableArgs),
+    [query, stableArgs]
+  );
+  const queryStateValue = queryState[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY;
+  const setQueryStateValue = useCallback(
+    (next) => {
+      setQueryState((prev) => {
+        const clone = { ...prev };
+        clone[queryKey] = typeof next === "function" ? next(clone[queryKey] ?? DEFAULT_QUERY_STATE_ENTRY) : next;
+        return clone;
+      });
+    },
+    [queryKey, setQueryState]
+  );
+  const [lastNonEmptyData, setLastNonEmptyData] = useState2();
+  useEffect(() => {
+    if (query.keepLastNonEmptyData && queryStateValue.data !== void 0) {
+      setLastNonEmptyData(queryStateValue.data);
+    }
+  }, [query.keepLastNonEmptyData, queryStateValue.data]);
+  const executeQuery = useCallback(
+    async (isRefetch) => {
+      query.log(
+        `Begin executing shared query ${queryKey}, isRefetch=${isRefetch}`
+      );
+      if (!isMounted.current) return;
+      setQueryStateValue((prev) => ({
+        // Keep old data and error.
+        ...prev,
+        lastUpdatedMs: Date.now(),
+        loading: true
+      }));
+      try {
+        let state;
+        if (isRefetch) {
+          const data = await query.refetch(...stableArgs);
+          const now = Date.now();
+          state = {
+            // Don't keep old error.
+            lastUpdatedMs: now,
+            loading: false,
+            data,
+            dataUpdatedMs: now
+          };
+        } else {
+          state = await query.getCachedOrFetch(...stableArgs);
+        }
+        if (!isMounted.current) return;
+        setQueryStateValue({ ...state, loading: false });
+        return state.data;
+      } catch (e) {
+        if (!isMounted.current) return;
+        const now = Date.now();
+        setQueryStateValue((prev) => ({
+          // Keep old data.
+          ...prev,
+          lastUpdatedMs: now,
+          loading: false,
+          error: e,
+          errorUpdatedMs: now
+        }));
+      }
+    },
+    [query, queryKey, setQueryStateValue, stableArgs]
+  );
+  useEffect(() => {
+    isMounted.current = true;
+    query.mount(queryKey);
+    void executeQuery(false);
+    return () => {
+      isMounted.current = false;
+      query.unmount(queryKey);
+    };
+  }, [executeQuery, query, queryKey]);
+  return useMemo2(() => {
+    return {
+      ...queryStateValue,
+      // Fill with lastNonEmptyData when data is undefined.
+      data: queryStateValue.data !== void 0 ? queryStateValue.data : lastNonEmptyData,
+      latestData: queryStateValue.data,
+      // 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.
+      abortCurrentQuery: (reason) => {
+        const controller = query.getAbortControllerByKey(queryKey);
+        controller?.abort(reason);
+        return Boolean(controller);
+      },
+      getCachedOrFetch: async () => {
+        const data = await query.getCachedOrFetch(...stableArgs);
+        return nonNil(
+          data.data,
+          typeof data.error === "string" ? data.error : JSON.stringify(data.error)
+        );
+      },
+      refetch: () => {
+        return executeQuery(true);
+      },
+      setData: (data, dataUpdatedMs) => {
+        query.setData(queryKey, data, dataUpdatedMs);
+      },
+      deleteData: () => {
+        query.deleteData(queryKey);
+      }
+    };
+  }, [
+    executeQuery,
+    lastNonEmptyData,
+    query,
+    queryKey,
+    queryStateValue,
+    stableArgs
+  ]);
+}
 export {
   SharedQueryConfig,
   SharedStateConfig,