@choksheak/react-utils 0.2.3 → 0.2.4

package/src/sharedQuery.ts

@@ -9,8 +9,9 @@ import {
   useSharedState,
 } from "./sharedState";
 import { stringifyDeterministicForKeys } from "./utils/stringify";
+import { useDeepMemo } from "./utils/useDeepMemo";
 
-export type FetchFn<TArgs extends unknown[], TData> = (
+export type QueryFn<TArgs extends unknown[], TData> = (
   ...args: TArgs
 ) => Promise<TData> | TData;
 
@@ -24,13 +25,34 @@ export type QueryStateValue<TData> = {
   loading: boolean;
   data?: TData;
   dataUpdatedMs?: number;
-  error?: Error;
+
+  /**
+   * Use unknown type for error because we can't assume what type of variable
+   * will be thrown from the query function. We also don't want to add this
+   * type to QueryStateValue<TError> as it adds complexity to the type.
+   */
+  error?: unknown;
+
   errorUpdatedMs?: number;
 };
 
 export type UseQueryResult<TData> = QueryStateValue<TData> & {
-  refetch: () => Promise<TData>;
+  /**
+   * Cancels the inflight query (if any). Returns true if canceled.
+   */
+  abortCurrentQuery: (reason?: unknown) => boolean;
+
+  /**
+   * Manually refresh the data by doing a new query.
+   */
+  refetch: () => void;
+
+  /**
+   * If you got the data from somewhere else (e.g. an in-memory data update),
+   * just set it directly.
+   */
   setData: (data: TData, dataUpdatedMs?: number) => void;
+
   deleteData: () => void;
 };
 
@@ -48,7 +70,7 @@ export type SharedQueryOptions<TArgs extends unknown[], TData> = {
   queryName: string;
 
   // Function to fetch data.
-  queryFn: FetchFn<TArgs, TData>;
+  queryFn: QueryFn<TArgs, TData>;
 
   // ms before data considered stale; 0 means always stale.
   staleMs?: number;
@@ -71,60 +93,81 @@ export type SharedQueryOptions<TArgs extends unknown[], TData> = {
   // Max number of bytes to keep. The oldest entries will be discarded.
   // The last record cannot be discarded. 0 means no limit.
   maxBytes?: number;
+
+  // Customize the logger.
+  log?: (...args: unknown[]) => void;
 } & SharedStateOptions<SharedQueryState<TData>>;
 
 /** Users can override these values globally. */
 export const SharedQueryDefaults = {
+  // Refetch on every page load.
   staleMs: 0,
+
+  // Keep in cache for a long time.
   expiryMs: 30 * MS_PER_DAY,
+
+  // Always refetch automatically if the data is stale.
+  refetchOnStale: true,
+
+  // No default persistence configured.
   persistTo: undefined as PersistTo | undefined,
-  maxSize: 100, // 100 is not too large, but please tweak accordingly
-  maxBytes: 100_000, // 100kb before GC
+
+  // 100 is not too large, but please tweak accordingly.
+  maxSize: 100,
+
+  // 100kb limit before discarding old records.
+  maxBytes: 100_000,
+
+  // Default to log to console.
+  log: (...args: unknown[]) => console.log("[sharedQuery]", ...args),
 };
 
 export class SharedQuery<TArgs extends unknown[], TData> {
-  private readonly inflightPromises = new Map<string, Promise<TData>>();
+  private readonly inflightQueries = new Map<
+    string,
+    { promise: Promise<TData>; abortController: AbortController }
+  >();
+
   public readonly queryState: SharedState<SharedQueryState<TData>>;
 
   public readonly queryName: string;
-  private readonly queryFn: FetchFn<TArgs, TData>;
+  private readonly queryFn: QueryFn<TArgs, TData>;
   public readonly expiryMs: number;
   public readonly staleMs: number;
   public readonly refetchOnStale: boolean;
   public readonly maxSize: number;
   public readonly maxBytes: number;
+  public readonly log: (...args: unknown[]) => void;
 
   public constructor(options: SharedQueryOptions<TArgs, TData>) {
     this.queryName = options.queryName;
-
     this.queryFn = options.queryFn;
 
-    this.expiryMs =
-      options?.expiryMs !== undefined
-        ? options?.expiryMs
-        : SharedQueryDefaults.expiryMs;
-
-    this.staleMs =
-      options?.staleMs !== undefined
-        ? options?.staleMs
-        : SharedQueryDefaults.staleMs;
+    this.staleMs = options?.staleMs ?? SharedQueryDefaults.staleMs;
+    this.expiryMs = options?.expiryMs ?? SharedQueryDefaults.expiryMs;
 
-    this.refetchOnStale = Boolean(options?.refetchOnStale);
+    this.refetchOnStale =
+      options?.refetchOnStale ?? SharedQueryDefaults.refetchOnStale;
 
     // Apply shortcut when using `persistTo`.
-    const persistTo = options.persistTo ?? SharedQueryDefaults.persistTo;
-
-    if (persistTo === "localStorage") {
-      options.localStorageKey = options.queryName;
-    } else if (persistTo === "indexedDb") {
-      options.indexedDbKey = options.queryName;
+    // Specifying the storage keys will take precedence over `persistTo`.
+    if (!options.localStorageKey && !options.indexedDbKey) {
+      const persistTo = options.persistTo ?? SharedQueryDefaults.persistTo;
+
+      if (persistTo === "localStorage") {
+        options.localStorageKey = options.queryName;
+      } else if (persistTo === "indexedDb") {
+        options.indexedDbKey = options.queryName;
+      }
     }
 
     this.maxSize = options?.maxSize ?? SharedQueryDefaults.maxSize;
     this.maxBytes = options?.maxBytes ?? SharedQueryDefaults.maxBytes;
 
+    this.log = options?.log ?? SharedQueryDefaults.log;
+
     this.queryState = sharedState<SharedQueryState<TData>>(
-      {},
+      {}, // defaultValue
       {
         ...options,
         // Fallback to use expiryMs for the storeExpiryMs.
@@ -133,10 +176,27 @@ export class SharedQuery<TArgs extends unknown[], TData> {
     );
   }
 
+  /** Returns a key to identify requests based on the given args. */
   public getQueryKey(args: TArgs): string {
     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.
+   */
+  public getAbortController(queryKey: string): AbortController | null {
+    return this.inflightQueries.get(queryKey)?.abortController ?? null;
+  }
+
+  /** Get the AbortSignal to check for query abortions. */
+  public getAbortSignal(queryKey: string): AbortSignal | null {
+    return this.getAbortController(queryKey)?.signal ?? null;
+  }
+
   private isStale(dataUpdatedMs: number): boolean {
     if (this.staleMs === 0) return true; // always stale
 
@@ -158,20 +218,18 @@ export class SharedQuery<TArgs extends unknown[], TData> {
     if (cached?.data && !this.isExpired(cached.dataUpdatedMs ?? 0)) {
       // Return cached value if not stale.
       if (!this.isStale(cached.dataUpdatedMs ?? 0)) {
-        console.log(
-          `Return fresh data ${queryKey} from cache without fetching`,
-        );
+        this.log(`Return fresh data ${queryKey} from cache without fetching`);
         return cached.data;
       }
 
       // If stale, optionally update the data in the background.
       if (this.refetchOnStale) {
-        console.log(`refetchOnStale for ${queryKey}`);
+        this.log(`refetchOnStale for ${queryKey}`);
         void this.dedupedFetch(queryKey, ...args);
       }
 
       // Still return stale data immediately.
-      console.log(`Returning stale data for ${queryKey}`);
+      this.log(`Returning stale data for ${queryKey}`);
       return cached.data;
     }
 
@@ -179,35 +237,37 @@ export class SharedQuery<TArgs extends unknown[], TData> {
   }
 
   private dedupedFetch(queryKey: string, ...args: TArgs): Promise<TData> {
-    const inflightPromise = this.inflightPromises.get(queryKey);
+    const inflightQuery = this.inflightQueries.get(queryKey);
 
     // De-duplicate in-flight requests
-    if (inflightPromise) {
-      console.log(`Deduplicating inflight fetch for ${queryKey}`);
-      return inflightPromise;
+    if (inflightQuery) {
+      this.log(`Deduplicating inflight fetch for ${queryKey}`);
+      return inflightQuery.promise;
     }
 
     // Fetch new data
     const promise = this.startFetching(queryKey, args);
+    const abortController = new AbortController();
+
+    this.inflightQueries.set(queryKey, { promise, abortController });
 
-    this.inflightPromises.set(queryKey, promise);
     return promise;
   }
 
   private async startFetching(queryKey: string, args: TArgs) {
-    console.log(`Start fetching ${queryKey}`);
+    this.log(`Start fetching ${queryKey}`);
 
     try {
       const data = await this.queryFn(...args);
 
-      console.log(`Successfully fetched ${queryKey}`);
+      this.log(`Successfully fetched ${queryKey}`);
       this.setData(queryKey, data, Date.now());
       return data;
     } catch (e) {
-      console.error(`Failed to fetch ${queryKey}: ${e}`);
+      this.log(`Failed to fetch ${queryKey}: ${e}`);
       throw e;
     } finally {
-      this.inflightPromises.delete(queryKey);
+      this.inflightQueries.delete(queryKey);
     }
   }
 
@@ -236,21 +296,30 @@ export class SharedQuery<TArgs extends unknown[], TData> {
   }
 
   /** Delete the cached data for one set of arguments. */
-  public deleteData(args: TArgs): void {
-    const queryKey = this.getQueryKey(args);
-
+  public deleteData(queryKey: string): void {
     const record = this.queryState.getSnapshot();
     const clone = { ...record };
     delete clone[queryKey];
     this.queryState.setValue(clone);
 
-    this.inflightPromises.delete(queryKey);
+    const inflight = this.inflightQueries.get(queryKey);
+    if (inflight) {
+      this.inflightQueries.delete(queryKey);
+      inflight.abortController.abort("Deleted");
+    }
   }
 
   /** Delete all currently cached data & all inflight promises. */
   public clear(): void {
     this.queryState.delete();
-    this.inflightPromises.clear();
+
+    for (const { abortController } of Array.from(
+      this.inflightQueries.values(),
+    )) {
+      abortController.abort("Cleared");
+    }
+
+    this.inflightQueries.clear();
   }
 
   /**
@@ -281,7 +350,7 @@ export class SharedQuery<TArgs extends unknown[], TData> {
       const numToCut = oldSize - this.maxSize;
 
       if (numToCut > 0) {
-        console.log(
+        this.log(
           `enforceSizeLimit for ${this.queryName} needed due to size ${oldSize} > ${this.maxSize}`,
         );
 
@@ -309,7 +378,7 @@ export class SharedQuery<TArgs extends unknown[], TData> {
       let bytesToCut = currentByteSize - this.maxBytes;
 
       if (bytesToCut > 0) {
-        console.log(
+        this.log(
           `enforceSizeLimit for ${this.queryName} needed due to byte size ${currentByteSize.toLocaleString()} > ${this.maxBytes.toLocaleString()}`,
         );
 
@@ -342,7 +411,7 @@ export class SharedQuery<TArgs extends unknown[], TData> {
       this.queryState.setValue(newState);
 
       // Log to inform user that the data was trimmed.
-      console.log(
+      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()})`,
       );
 
@@ -350,7 +419,7 @@ export class SharedQuery<TArgs extends unknown[], TData> {
     }
 
     // Log to indicate why trimming was not needed.
-    console.log(
+    this.log(
       `No need to trim data for ${this.queryName}: size=${oldSize} (limit=${this.maxSize}), byteSize=${oldByteSize.toLocaleString()} (limit=${this.maxBytes.toLocaleString()})`,
     );
   }
@@ -406,80 +475,88 @@ export function useSharedQuery<TArgs extends unknown[], TData>(
   // Default to use no arguments.
   args: TArgs = [] as unknown as TArgs,
 ): UseQueryResult<TData> {
+  // We don't expect users to provide a stable `args`, so stabilize it here.
+  const stableArgs = useDeepMemo(args);
+
   const [queryState, setQueryState] = useSharedState(query.queryState);
 
   const isMounted = useRef(true);
 
-  // Identify args changes using deep equality.
-  // We intentionally chose not to memoize this value because args is likely
-  // to be an unstable value (changes on every render).
-  const queryKey = query.getQueryKey(args);
+  const queryKey = useMemo(
+    () => query.getQueryKey(stableArgs),
+    [query, stableArgs],
+  );
 
-  // The fetch logic wrapped in useCallback to be stable for useEffect
-  const execute = useCallback(async () => {
-    console.log(`Begin executing shared query ${queryKey}`);
+  // Make sure typechecker knows this could be undefined.
+  const queryStateValue = queryState[queryKey] as
+    | QueryStateValue<TData>
+    | undefined;
 
-    setQueryState((prev) => {
-      const clone = { ...prev };
-
-      clone[queryKey] = {
-        ...(clone[queryKey] ?? {}),
-        lastUpdatedMs: Date.now(),
-        loading: true,
-      };
-
-      return clone;
-    });
-
-    try {
-      const data = await query.getCachedOrFetch(...args);
-
-      if (isMounted.current) {
-        setQueryState((prev) => {
-          const clone = { ...prev };
-          const now = Date.now();
-
-          clone[queryKey] = {
-            // Don't keep old error.
-            lastUpdatedMs: now,
-            loading: false,
-            data,
-            dataUpdatedMs: now,
-          };
-
-          return clone;
-        });
-      }
-    } catch (e) {
-      const error =
-        e instanceof Error
-          ? e
-          : new Error(`An unknown error occurred during fetch: ${e}`);
-
-      if (isMounted.current) {
-        setQueryState((prev) => {
-          const clone = { ...prev };
-          const now = Date.now();
-
-          clone[queryKey] = {
-            // Keep old data.
-            ...(clone[queryKey] ?? {}),
-            lastUpdatedMs: now,
-            loading: false,
-            error,
-            errorUpdatedMs: now,
-          };
-
-          return clone;
-        });
+  // The fetch logic wrapped in useCallback to be stable for useEffect
+  const execute = useCallback(
+    async (forceRefresh: boolean) => {
+      query.log(`Begin executing shared query ${queryKey}`);
+
+      setQueryState((prev) => {
+        const clone = { ...prev };
+
+        clone[queryKey] = {
+          ...(clone[queryKey] ?? {}),
+          lastUpdatedMs: Date.now(),
+          loading: true,
+        };
+
+        return clone;
+      });
+
+      try {
+        const data = await (forceRefresh
+          ? query.updateFromSource(...stableArgs)
+          : query.getCachedOrFetch(...stableArgs));
+
+        if (isMounted.current) {
+          setQueryState((prev) => {
+            const clone = { ...prev };
+            const now = Date.now();
+
+            clone[queryKey] = {
+              // Don't keep old error.
+              lastUpdatedMs: now,
+              loading: false,
+              data,
+              dataUpdatedMs: now,
+            };
+
+            return clone;
+          });
+        }
+      } catch (e) {
+        if (isMounted.current) {
+          setQueryState((prev) => {
+            const clone = { ...prev };
+            const now = Date.now();
+
+            clone[queryKey] = {
+              // Keep old data.
+              ...(clone[queryKey] ?? {}),
+              lastUpdatedMs: now,
+              loading: false,
+              error: e,
+              errorUpdatedMs: now,
+            };
+
+            return clone;
+          });
+        }
       }
-    }
-  }, [queryKey]);
+    },
+    [query, queryKey, setQueryState, stableArgs],
+  );
 
   useEffect(() => {
     isMounted.current = true;
 
-    void execute();
+    void execute(false);
 
     return () => {
       isMounted.current = false;
@@ -488,20 +565,24 @@ export function useSharedQuery<TArgs extends unknown[], TData>(
 
   return useMemo(() => {
     const state =
-      queryState[queryKey] ??
-      (DEFAULT_QUERY_STATE_ENTRY as QueryStateValue<TData>);
+      queryStateValue ?? (DEFAULT_QUERY_STATE_ENTRY as QueryStateValue<TData>);
 
     return {
       ...state,
+      abortCurrentQuery: (reason?: unknown) => {
+        const controller = query.getAbortController(queryKey);
+        controller?.abort(reason);
+        return Boolean(controller);
+      },
       refetch: () => {
-        return query.updateFromSource(...args);
+        void execute(true);
       },
       setData: (data: TData, dataUpdatedMs?: number) => {
         query.setData(queryKey, data, dataUpdatedMs ?? Date.now());
       },
       deleteData: () => {
-        query.deleteData(args);
+        query.deleteData(queryKey);
       },
     };
-  }, [query, queryKey, queryState]);
+  }, [execute, query, queryKey, queryStateValue]);
 }

package/src/utils/useDeepMemo.ts

@@ -0,0 +1,19 @@
+import isEqual from "lodash/isEqual";
+import { useMemo, useState } from "react";
+
+/** Provides a stable value for T based on deep equality. */
+export function useDeepMemo<T>(value: T): T {
+  const [state, setState] = useState<T>(value);
+
+  return useMemo(() => {
+    if (state === value || isEqual(state, value)) {
+      return state;
+    }
+
+    // We check equality, so this should be safe.
+    // eslint-disable-next-line react-hooks/set-state-in-render
+    setState(value);
+
+    return value;
+  }, [state, value]);
+}

package/utils/useDeepMemo.d.mts

@@ -0,0 +1,4 @@
+/** Provides a stable value for T based on deep equality. */
+declare function useDeepMemo<T>(value: T): T;
+
+export { useDeepMemo };

package/utils/useDeepMemo.d.ts

@@ -0,0 +1,2 @@
+/** Provides a stable value for T based on deep equality. */
+export declare function useDeepMemo<T>(value: T): T;

package/utils/useDeepMemo.js

@@ -0,0 +1,51 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/useDeepMemo.ts
+var useDeepMemo_exports = {};
+__export(useDeepMemo_exports, {
+  useDeepMemo: () => useDeepMemo
+});
+module.exports = __toCommonJS(useDeepMemo_exports);
+var import_isEqual = __toESM(require("lodash/isEqual"));
+var import_react = require("react");
+function useDeepMemo(value) {
+  const [state, setState] = (0, import_react.useState)(value);
+  return (0, import_react.useMemo)(() => {
+    if (state === value || (0, import_isEqual.default)(state, value)) {
+      return state;
+    }
+    setState(value);
+    return value;
+  }, [state, value]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useDeepMemo
+});

package/utils/useDeepMemo.mjs

@@ -0,0 +1,16 @@
+// src/utils/useDeepMemo.ts
+import isEqual from "lodash/isEqual";
+import { useMemo, useState } from "react";
+function useDeepMemo(value) {
+  const [state, setState] = useState(value);
+  return useMemo(() => {
+    if (state === value || isEqual(state, value)) {
+      return state;
+    }
+    setState(value);
+    return value;
+  }, [state, value]);
+}
+export {
+  useDeepMemo
+};

package/docs/.nojekyll

@@ -1 +0,0 @@
-TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/docs/assets/hierarchy.js

@@ -1 +0,0 @@
-window.hierarchyData = "eJyrVirKzy8pVrKKjtVRKkpNy0lNLsnMzytWsqqurQUAmx4Kpg=="