@choksheak/react-utils 0.3.6 → 0.3.8

package/sharedQuery.mjs

@@ -15,7 +15,7 @@ import { useSyncExternalStore } from "react";
 
 // src/storage.ts
 import { kvStore } from "@choksheak/ts-utils/kvStore";
-import { LocalStore } from "@choksheak/ts-utils/localStore";
+import { createLocalStore } from "@choksheak/ts-utils/localStore";
 var IS_NOT_BROWSER = typeof window === "undefined";
 function getStorageAdapter(options, defaultStoreExpiryMs) {
   const { store } = options ?? {};
@@ -24,70 +24,12 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
     const expiryMs = store.expiryMs || defaultStoreExpiryMs;
-    const isValid = store.isValid;
+    const config = { ...store, expiryMs };
     switch (store.persistTo) {
-      case "localStorage": {
-        const adapter = new LocalStore(store.key, {
-          defaultExpiryMs: expiryMs
-        });
-        return {
-          set: (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.set(key, value);
-          },
-          get: (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const value = adapter.get(key);
-            if (isValid && !isValid(value)) {
-              console.warn(
-                `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              adapter.delete(key);
-              return void 0;
-            }
-            return value;
-          },
-          delete: (key) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.delete(key);
-          },
-          clear: () => {
-            if (IS_NOT_BROWSER) return;
-            adapter.clear();
-          }
-        };
-      }
-      case "indexedDb": {
-        const keyPrefix = store.key + ":";
-        const isValid2 = store.isValid;
-        return {
-          set: async (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.set(keyPrefix + key, value, expiryMs);
-          },
-          get: async (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const fullKey = keyPrefix + key;
-            const value = await kvStore.get(fullKey);
-            if (isValid2 && !isValid2(value)) {
-              console.warn(
-                `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              await kvStore.delete(fullKey);
-              return void 0;
-            }
-            return value;
-          },
-          delete: async (key) => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.delete(keyPrefix + key);
-          },
-          clear: async () => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.clear();
-          }
-        };
-      }
+      case "localStorage":
+        return localStoreAdapter(config);
+      case "indexedDb":
+        return kvStoreAdapter(config);
       default:
         store.persistTo;
         throw new Error(`Unknown store.adapter ${store.persistTo}`);
@@ -95,6 +37,74 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   return store;
 }
+function localStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const adapter = createLocalStore(key, { defaultExpiryMs: expiryMs });
+  return {
+    set: (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.set(key2, value);
+    },
+    get: (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const value = adapter.get(key2);
+      if (isValid && !isValid(value)) {
+        console.warn(
+          `localStorage adapter: Auto-discard invalid value for ${key2}: ${JSON.stringify(value)}`
+        );
+        adapter.delete(key2);
+        return void 0;
+      }
+      return value;
+    },
+    delete: (key2) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.delete(key2);
+    },
+    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 = {
@@ -109,41 +119,11 @@ var SharedStateConfig = {
    */
   lazyLoad: false
 };
-var PubSubStore = class {
-  dataByKey = /* @__PURE__ */ new Map();
-  subscribersByKey = /* @__PURE__ */ new Map();
-  // 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 this.dataByKey.get(key);
-  }
-  set(key, value) {
-    const prev = this.dataByKey.get(key);
-    if (prev === value) return;
-    this.dataByKey.set(key, value);
-    this.notify(key, value, prev);
-  }
-  delete(key) {
-    this.dataByKey.delete(key);
-  }
-  setNoNotify(key, value) {
-    this.dataByKey.set(key, value);
-  }
-  // Subscribe to changes of a specific key
-  subscribe(key, subscriber) {
-    let subscribers = this.subscribersByKey.get(key);
-    if (!subscribers) {
-      subscribers = /* @__PURE__ */ new Set();
-      this.subscribersByKey.set(key, subscribers);
-    }
-    subscribers.add(subscriber);
-    return () => {
-      subscribers.delete(subscriber);
-      if (subscribers.size === 0) this.subscribersByKey.delete(key);
-    };
-  }
-  notify(key, next, prev) {
-    const subscribers = this.subscribersByKey.get(key);
+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) {
@@ -154,116 +134,139 @@ var PubSubStore = class {
       }
     }
   }
-};
-var pubSubStore = new PubSubStore();
+  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);
+      };
+    }
+  };
+}
+var pubSubStore = createPubSubStore();
 var STORAGE_KEY = "state";
 var stateKey = 0;
-var SharedState = class {
-  constructor(defaultValue, options) {
-    this.defaultValue = defaultValue;
-    let readyResolve = () => {
-    };
-    this.readyPromise = new Promise((resolve) => {
-      readyResolve = resolve;
-    });
-    this.resolveReadyPromise = readyResolve;
-    this.pubSubKey = String(stateKey++);
-    this.storageAdapter = getStorageAdapter(
-      options,
-      SharedStateConfig.storeExpiryMs
-    );
-    this.setValueBounded = (next) => {
-      this.setValue(next);
-    };
-    pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
-    const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
-    if (!lazy) {
-      void this.initDefaultValueOnce();
-    }
-  }
-  pubSubKey;
-  storageAdapter;
-  setValueBounded;
-  initStarted = false;
-  initDone = false;
-  // Allow users to await for the completion of data init.
-  readyPromise;
-  resolveReadyPromise;
-  /** `subscribe` function required by useSyncExternalStore. */
-  subscribe(subscriber) {
-    return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
-  }
-  /** Returns true if there is a backing store. */
-  hasStore() {
-    return Boolean(this.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.
-   */
-  async setInStore(value) {
-    return await this.storageAdapter?.set(STORAGE_KEY, value);
-  }
-  /**
-   * Get a value directly from the store. Returns undefined if there is no
-   * backing store.
-   */
-  async getFromStore() {
-    return await this.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(this.pubSubKey);
-  }
-  /** Set the value of the shared state. */
-  setValue(next) {
-    if (typeof next === "function") {
-      const prev = pubSubStore.get(this.pubSubKey);
-      next = next(prev);
+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;
+  const obj = {
+    /** 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.
+     */
+    async setInStore(value) {
+      return await storageAdapter?.set(STORAGE_KEY, value);
+    },
+    /**
+     * Get a value directly from the store. Returns undefined if there is no
+     * backing store.
+     */
+    async getFromStore() {
+      return await 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);
+      void storageAdapter?.set(STORAGE_KEY, defaultValue);
+    },
+    /** Initial default handling. */
+    async initDefaultValueOnce() {
+      if (obj.initDone || obj.initStarted) return;
+      obj.initStarted = true;
+      const stored = await obj.getFromStore();
+      const value = stored !== void 0 ? stored : defaultValue;
+      pubSubStore.set(pubSubKey, value);
+      obj.initDone = true;
+      resolveReadyPromise();
     }
-    pubSubStore.set(this.pubSubKey, next);
-    void this.setInStore(next);
+  };
+  if (!lazy) {
+    void obj.initDefaultValueOnce();
   }
-  /**
-   * Remove the value of the shared state. Actually this just sets the value
-   * back to the given default value.
-   */
-  delete() {
-    pubSubStore.set(this.pubSubKey, this.defaultValue);
-    void this.storageAdapter?.set(STORAGE_KEY, this.defaultValue);
-  }
-  /** Initial default handling. */
-  async initDefaultValueOnce() {
-    if (this.initDone || this.initStarted) return;
-    this.initStarted = true;
-    const stored = await this.getFromStore();
-    const value = stored !== void 0 ? stored : this.defaultValue;
-    pubSubStore.set(this.pubSubKey, value);
-    this.initDone = true;
-    this.resolveReadyPromise();
-  }
-};
-function sharedState(defaultValue, options) {
-  return new SharedState(defaultValue, options);
+  return obj;
 }
 function useSharedState(state) {
-  state.initDefaultValueOnce();
+  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.setValueBounded];
+  return [value, state.setValue];
 }
 
 // src/stringify.ts
@@ -303,7 +306,7 @@ import { useMemo, useState } from "react";
 function useDeepMemo(value) {
   const [state, setState] = useState(value);
   return useMemo(() => {
-    if (state === value || isEqual(state, value)) {
+    if (isEqual(state, value)) {
       return state;
     }
     setState(value);
@@ -331,282 +334,104 @@ var SharedQueryConfig = {
 function configureSharedQuery(config) {
   Object.assign(SharedQueryConfig, config);
 }
-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;
-  refetchFn;
-  expiryMs;
-  staleMs;
-  refetchOnStale;
-  maxSize;
-  maxBytes;
-  keepLastNonEmptyData;
-  log;
-  constructor(options) {
-    this.queryName = options.queryName;
-    this.queryFn = options.queryFn;
-    this.refetchFn = options.refetchFn;
-    this.staleMs = options?.staleMs ?? SharedQueryConfig.staleMs;
-    this.expiryMs = options?.expiryMs ?? SharedQueryConfig.expiryMs;
-    this.refetchOnStale = options?.refetchOnStale ?? SharedQueryConfig.refetchOnStale;
-    if (!options.store) {
-      const persistTo = options.persistTo ?? SharedQueryConfig.persistTo;
-      if (persistTo) {
-        options.store = {
+var seenQueryNames = /* @__PURE__ */ new Set();
+function sharedQuery(options) {
+  if (seenQueryNames.has(options.queryName)) {
+    throw new Error(`Duplicate shared query name "${options.queryName}"`);
+  }
+  seenQueryNames.add(options.queryName);
+  const inflightQueries = /* @__PURE__ */ new Map();
+  const mountedKeys = /* @__PURE__ */ new Map();
+  const queryName = options.queryName;
+  const queryFn = options.queryFn;
+  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: options.queryName,
-          expiryMs: this.expiryMs
-        };
-      }
+          key: queryName,
+          expiryMs
+        }
+      };
     }
-    this.maxSize = options?.maxSize ?? SharedQueryConfig.maxSize;
-    this.maxBytes = options?.maxBytes ?? SharedQueryConfig.maxBytes;
-    this.keepLastNonEmptyData = Boolean(options?.keepLastNonEmptyData);
-    this.log = options?.log ?? SharedQueryConfig.log;
-    this.queryState = sharedState(
-      {},
-      // defaultValue
-      options
-    );
   }
-  /** Returns a key to identify requests based on the given args. */
-  getQueryKey(args) {
-    return this.queryName + ":" + stringifyDeterministicForKeys(args);
-  }
-  /**
-   * Get the AbortController to abort the inflight query (if any).
-   *
-   * Note that once you get the controller, you can also get the signal easily
-   * using `controller.signal`. So if you need both the controller and the
-   * signal, just use this function.
-   */
-  getAbortController(args) {
-    const queryKey = this.getQueryKey(args);
-    return this.getAbortControllerByKey(queryKey);
-  }
-  getAbortControllerByKey(queryKey) {
-    return this.inflightQueries.get(queryKey)?.abortController ?? null;
-  }
-  /**
-   * Get the AbortSignal to check for query abortions.
-   *
-   * Example:
-   * ```
-   *   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();
-   *     },
-   *   });
-   * ```
-   */
-  getAbortSignal(args) {
-    const queryKey = this.getQueryKey(args);
-    return this.getAbortSignalByKey(queryKey);
-  }
-  getAbortSignalByKey(queryKey) {
-    return this.getAbortControllerByKey(queryKey)?.signal ?? null;
-  }
-  isStale(dataUpdatedMs) {
-    if (this.staleMs === 0) return true;
+  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 > this.staleMs;
+    return ageMs > staleMs;
   }
-  isExpired(dataUpdatedMs) {
-    if (this.expiryMs === 0) return false;
+  function isExpired(dataUpdatedMs) {
+    if (expiryMs === 0) return false;
     const ageMs = Date.now() - dataUpdatedMs;
-    return ageMs > this.expiryMs;
+    return ageMs > expiryMs;
   }
-  /** For cached data, we need to return the correct timestamps as well. */
-  async getCachedOrFetch(...args) {
-    const startMs = Date.now();
-    await this.queryState.readyPromise;
-    const waitedMs = Date.now() - startMs;
-    const queryKey = this.getQueryKey(args);
-    const cached = this.queryState.getSnapshot()?.[queryKey];
-    if (waitedMs) {
-      this.log(`${queryKey}: Waited for ${waitedMs}ms before data is ready`);
-    }
-    if (cached?.data && !this.isExpired(cached.dataUpdatedMs ?? 0)) {
-      if (!this.isStale(cached.dataUpdatedMs ?? 0)) {
-        this.log(`Return fresh data ${queryKey} from cache without fetching`);
-        return cached;
-      }
-      if (this.refetchOnStale) {
-        this.log(`refetchOnStale for ${queryKey}`);
-        void this.dedupedFetch(queryKey, "query", ...args);
-      }
-      this.log(`Returning stale data for ${queryKey}`);
-      return cached;
-    }
-    const data = await this.dedupedFetch(queryKey, "query", ...args);
-    const now = Date.now();
-    return {
-      // Don't keep old error.
-      lastUpdatedMs: now,
-      loading: false,
-      data,
-      dataUpdatedMs: now
-    };
-  }
-  dedupedFetch(queryKey, queryType, ...args) {
-    const inflightQuery = this.inflightQueries.get(queryKey);
-    if (inflightQuery) {
-      this.log(
-        `Deduplicating inflight fetch for ${queryKey}, queryType=${queryType}`
-      );
-      return inflightQuery.promise;
-    }
-    const promise = this.startFetching(queryKey, queryType, args);
-    const abortController = new AbortController();
-    this.inflightQueries.set(queryKey, { promise, abortController });
-    return promise;
-  }
-  async startFetching(queryKey, queryType, args) {
-    this.log(`Start fetching ${queryKey}, queryType=${queryType}`);
-    try {
-      const data = await (queryType === "refetch" && this.refetchFn ? this.refetchFn(...args) : this.queryFn(...args));
-      this.log(`Successfully fetched ${queryKey}`);
-      this.setData(queryKey, data, Date.now());
-      return data;
-    } catch (e) {
-      this.log(`Failed to fetch ${queryKey} for queryType=${queryType}: ${e}`);
-      throw e;
-    } finally {
-      this.inflightQueries.delete(queryKey);
-    }
-  }
-  /** Get the entire stored entry for a query key. */
-  getQueryValue(queryKey) {
-    return this.queryState.getSnapshot()?.[queryKey];
-  }
-  /** Get the current stored data for a query key. */
-  getData(queryKey) {
-    const stateValue = this.queryState.getSnapshot()?.[queryKey];
-    if (stateValue?.lastUpdatedMs) {
-      if (this.isExpired(stateValue.lastUpdatedMs)) {
-        this.deleteData(queryKey);
-        return void 0;
-      }
-    }
-    return stateValue?.data;
-  }
-  /** Set the data directly if the user obtained it from somewhere else. */
-  setData(queryKey, data, dataUpdatedMs = Date.now()) {
-    const entry = {
-      lastUpdatedMs: Date.now(),
-      loading: false,
-      data,
-      dataUpdatedMs
-    };
-    this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
-    this.enforceSizeLimit();
-  }
-  /**
-   * Do a new fetch even when the data is already cached, but don't fetch if
-   * another fetch is already inflight.
-   */
-  async updateFromSource(...args) {
-    const key = this.getQueryKey(args);
-    return await this.dedupedFetch(key, "query", ...args);
-  }
-  /**
-   * Perform an explicit refetch. If `options.refetchFn` was not specified,
-   * then this would be identical to calling `this.updateFromSource()`.
-   */
-  async refetch(...args) {
-    const key = this.getQueryKey(args);
-    return await this.dedupedFetch(key, "refetch", ...args);
-  }
-  /** Delete the cached data for one set of arguments. */
-  deleteData(queryKey) {
-    const record = this.queryState.getSnapshot();
-    const clone = { ...record };
-    delete clone[queryKey];
-    this.queryState.setValue(clone);
-    const inflight = this.inflightQueries.get(queryKey);
-    if (inflight) {
-      this.inflightQueries.delete(queryKey);
-      inflight.abortController.abort("Deleted");
-    }
-  }
-  /** Delete all currently cached data & all inflight promises. */
-  clear() {
-    this.queryState.delete();
-    for (const { abortController } of Array.from(
-      this.inflightQueries.values()
-    )) {
-      abortController.abort("Cleared");
-    }
-    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.
-   */
-  enforceSizeLimit() {
-    if (!this.maxSize && !this.maxBytes) {
+  function enforceSizeLimit() {
+    if (!maxSize && !maxBytes) {
       return;
     }
-    const oldState = this.queryState.getSnapshot();
+    const oldState = queryState.getSnapshot();
     const oldSize = Object.keys(oldState).length;
     if (oldSize <= 1) {
       return;
     }
     const oldByteSize = getByteSize(oldState);
-    let numToCut = this.maxSize ? oldSize - this.maxSize : 0;
-    let bytesToCut = this.maxBytes ? oldByteSize - this.maxBytes : 0;
+    let numToCut = maxSize ? oldSize - maxSize : 0;
+    let bytesToCut = maxBytes ? oldByteSize - 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()})`
+      log(
+        `No need to trim data for ${queryName}: size=${oldSize} (limit=${maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${maxBytes.toLocaleString()})`
       );
       return;
     }
-    this.log(
-      `Need to trim ${this.queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`
+    log(
+      `Need to trim ${queryName}: numToCut=${numToCut}, bytesToCut=${bytesToCut}`
     );
     const newState = { ...oldState };
     let needUpdate = false;
     const deleteKeyIfNotMounted = (key, expired) => {
-      if (this.mountedKeys.has(key)) {
-        this.log(`Cannot clean up ${key} as it is mounted`);
+      if (mountedKeys.has(key)) {
+        log(`Cannot clean up ${key} as it is mounted`);
         return;
       }
       const byteSize = getByteSize(key) + getByteSize(newState[key]);
-      this.log(
+      log(
         `Cleaning up unmounted${expired ? ", expired" : ""} ${key} (byteSize=${byteSize.toLocaleString()})`
       );
       numToCut--;
@@ -618,7 +443,7 @@ var SharedQuery = class {
       (entry1, entry2) => entry1[1].lastUpdatedMs - entry2[1].lastUpdatedMs
     );
     for (const [key] of entriesByTimeAscending) {
-      if (!this.isExpired(newState[key].lastUpdatedMs)) {
+      if (!isExpired(newState[key].lastUpdatedMs)) {
         break;
       }
       deleteKeyIfNotMounted(key, true);
@@ -637,24 +462,220 @@ var SharedQuery = class {
       }
     }
     if (!needUpdate) {
-      this.log(
-        `No trimmable entries found for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`
+      log(
+        `No trimmable entries found for ${queryName}: size=${oldSize} (limit=${maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${maxBytes.toLocaleString()})`
       );
       return;
     }
-    this.queryState.setValue(newState);
-    this.log(
-      `Trimmed data for ${this.queryName}: size=[${oldSize} -> ${Object.keys(newState).length}] (limit=${this.maxSize}), byteSize=[${oldByteSize.toLocaleString()} -> ${getByteSize(newState).toLocaleString()}] (limit=${this.maxBytes.toLocaleString()})`
+    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()})`
     );
   }
-};
-var seenQueryNames = /* @__PURE__ */ new Set();
-function sharedQuery(options) {
-  if (seenQueryNames.has(options.queryName)) {
-    throw new Error(`Duplicate shared query "${options.queryName}"`);
+  function setData(queryKey, data, dataUpdatedMs = Date.now()) {
+    const entry = {
+      lastUpdatedMs: Date.now(),
+      loading: false,
+      data,
+      dataUpdatedMs
+    };
+    queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+    enforceSizeLimit();
   }
-  seenQueryNames.add(options.queryName);
-  return new SharedQuery(options);
+  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) {
+      return queryName + ":" + stringifyDeterministicForKeys(args);
+    },
+    /**
+     * Get the AbortController to abort the inflight query (if any).
+     *
+     * Note that once you get the controller, you can also get the signal easily
+     * using `controller.signal`. So if you need both the controller and the
+     * signal, just use this function.
+     */
+    getAbortController(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:
+     * ```
+     *   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();
+     *     },
+     *   });
+     * ```
+     */
+    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;
 }
 var DEFAULT_QUERY_STATE_ENTRY = {
   lastUpdatedMs: 0,
@@ -751,38 +772,18 @@ function useSharedQuery(query, ...args) {
         return Boolean(controller);
       },
       refetch: () => {
-        void execute(true);
+        return execute(true);
       },
       setData: (data, dataUpdatedMs) => {
-        const now = Date.now();
-        setQueryStateValue((prev) => ({
-          ...prev,
-          data,
-          dataUpdatedMs: dataUpdatedMs ?? now,
-          lastUpdatedMs: now,
-          loading: false
-        }));
+        query.setData(queryKey, data, dataUpdatedMs);
       },
       deleteData: () => {
-        setQueryState((prev) => {
-          const clone = { ...prev };
-          delete clone[queryKey];
-          return clone;
-        });
+        query.deleteData(queryKey);
       }
     };
-  }, [
-    execute,
-    lastNonEmptyData,
-    query,
-    queryKey,
-    queryStateValue,
-    setQueryState,
-    setQueryStateValue
-  ]);
+  }, [execute, lastNonEmptyData, query, queryKey, queryStateValue]);
 }
 export {
-  SharedQuery,
   SharedQueryConfig,
   configureSharedQuery,
   sharedQuery,