@choksheak/react-utils 0.1.6 → 0.1.7

package/src/sharedQuery.ts

@@ -0,0 +1,303 @@
+import { DEFAULT_EXPIRY_DELTA_MS } from "@choksheak/ts-utils/kvStore";
+import { useCallback, useEffect, useRef } from "react";
+
+import { SharedState, sharedState, useSharedState } from "./sharedState";
+import { StorageOptions } from "./utils/storage";
+import { stringifyDeterministicForKeys } from "./utils/stringify";
+
+export type FetchFn<TArgs extends unknown[], TResult> = (
+  ...args: TArgs
+) => Promise<TResult>;
+
+export type FetchedData<TResult> = {
+  value: TResult;
+  updatedMs: number;
+};
+
+export type QueryStateValue<TResult> = {
+  data: FetchedData<TResult> | null;
+  loading: boolean;
+  error: Error | null;
+};
+
+/**
+ * The full query state is a record of all the fetch results mapped by
+ * query key to the state entry.
+ */
+export type SharedQueryState<TResult> = Record<
+  string,
+  QueryStateValue<TResult>
+>;
+
+export type SharedQueryOptions<TResult> = {
+  // ms before data considered stale; 0 means never stale.
+  staleMs?: number;
+  // ms before data is removed from cache; 0 means never expire.
+  expiryMs?: number;
+  // Trigger background re-fetch if stale.
+  revalidateOnStale?: boolean;
+} & StorageOptions<SharedQueryState<TResult>>;
+
+const DEFAULT_STALE_MS = 0;
+
+export class SharedQuery<TArgs extends unknown[], TResult> {
+  private readonly inflightPromises = new Map<string, Promise<TResult>>();
+  public readonly queryState: SharedState<SharedQueryState<TResult>>;
+  public readonly expiryMs: number;
+  public readonly staleMs: number;
+  public readonly revalidateOnStale: boolean;
+
+  public constructor(
+    public readonly queryName: string,
+    private readonly fetchFn: FetchFn<TArgs, TResult>,
+    options?: SharedQueryOptions<TResult>,
+  ) {
+    this.expiryMs =
+      options?.expiryMs !== undefined
+        ? options?.expiryMs
+        : DEFAULT_EXPIRY_DELTA_MS;
+
+    this.staleMs =
+      options?.staleMs !== undefined ? options?.staleMs : DEFAULT_STALE_MS;
+
+    this.revalidateOnStale = Boolean(options?.revalidateOnStale);
+
+    this.queryState = sharedState<SharedQueryState<TResult>>(
+      {},
+      {
+        ...options,
+        // Fallback to use expiryMs for the storeExpiryMs.
+        storeExpiryMs: options?.storeExpiryMs || this.expiryMs,
+      },
+    );
+  }
+
+  public getQueryKey(args: TArgs): string {
+    return this.queryName + ":" + stringifyDeterministicForKeys(args);
+  }
+
+  private isStale(entry: FetchedData<TResult>): boolean {
+    if (this.staleMs === 0) return true; // always stale
+
+    const ageMs = Date.now() - entry.updatedMs;
+    return ageMs > this.staleMs;
+  }
+
+  private isExpired(entry: FetchedData<TResult>): boolean {
+    if (this.expiryMs === 0) return false; // never expire
+
+    const ageMs = Date.now() - entry.updatedMs;
+    return ageMs > this.expiryMs;
+  }
+
+  private fetchNoCaching(queryKey: string, ...args: TArgs): Promise<TResult> {
+    const inflightPromise = this.inflightPromises.get(queryKey);
+
+    // De-duplicate in-flight requests
+    if (inflightPromise) {
+      console.log(`Deduplicating inflight fetch for ${queryKey}`);
+      return inflightPromise;
+    }
+
+    // Fetch new data
+    console.log(`Start fetching ${queryKey}`);
+
+    const promise = this.fetchFn(...args)
+      .then((result) => {
+        console.log(`Successfully fetched ${queryKey}`);
+        this.setCache(queryKey, result);
+        return result;
+      })
+      .catch((e) => {
+        console.error(`Failed to fetch ${queryKey}: ${e}`);
+        throw e;
+      })
+      .finally(() => {
+        this.inflightPromises.delete(queryKey);
+      });
+
+    this.inflightPromises.set(queryKey, promise);
+    return promise;
+  }
+
+  public async getCachedOrFetch(...args: TArgs): Promise<TResult> {
+    const queryKey = this.getQueryKey(args);
+    const cached = this.queryState.getSnapshot()?.[queryKey];
+
+    if (cached?.data && !this.isExpired(cached.data)) {
+      // Return cached value if not stale.
+      if (!this.isStale(cached.data)) {
+        console.log(
+          `Return fresh data ${queryKey} from cache without fetching`,
+        );
+        return cached.data.value;
+      }
+
+      // If stale, optionally update the data in the background.
+      if (this.revalidateOnStale) {
+        console.log(`revalidateOnStale for ${queryKey}`);
+        void this.fetchNoCaching(queryKey, ...args);
+      }
+
+      // Still return stale data immediately.
+      console.log(`Returning stale data for ${queryKey}`);
+      return cached.data.value;
+    }
+
+    return await this.fetchNoCaching(queryKey, ...args);
+  }
+
+  private async setCache(queryKey: string, value: TResult): Promise<void> {
+    const entry: QueryStateValue<TResult> = {
+      data: { value, updatedMs: Date.now() },
+      loading: false,
+      error: null,
+    };
+
+    this.queryState.setValue((prev) => ({ ...prev, [queryKey]: entry }));
+  }
+
+  /** Do a new fetch even when the data is already cached. */
+  public async updateFromSource(...args: TArgs): Promise<TResult> {
+    const key = this.getQueryKey(args);
+    return await this.fetchNoCaching(key, ...args);
+  }
+
+  /** Delete the currently cached data. */
+  public invalidate(args?: TArgs): void {
+    if (args) {
+      const queryKey = this.getQueryKey(args);
+
+      const record = this.queryState.getSnapshot();
+      const clone = { ...record };
+      delete clone[queryKey];
+      this.queryState.setValue(clone);
+
+      this.inflightPromises.delete(queryKey);
+    } else {
+      this.clearAll();
+    }
+  }
+
+  /** Delete the currently cached data & all inflight promises. */
+  public clearAll(): void {
+    this.queryState.delete();
+    this.inflightPromises.clear();
+  }
+}
+
+const seenQueryNames = new Set<string>();
+
+/**
+ * Create a reusable shared query object that can be used to auto de-duplicate
+ * and cache all data fetches, with auto-expiration and staleness checks.
+ *
+ * Each `queryName` must be unique, and can only be declared once, most often
+ * in the top level scope. The queryName is used for logging only.
+ */
+export function sharedQuery<TArgs extends unknown[], TResult>(
+  // The name could have been auto-generated, but we let the user give us a
+  // human-readable name that can be identified quickly in the logs.
+  queryName: string,
+  fetchFn: FetchFn<TArgs, TResult>,
+  options?: SharedQueryOptions<TResult>,
+): SharedQuery<TArgs, TResult> {
+  if (seenQueryNames.has(queryName)) {
+    throw new Error(`Duplicate shared query "${queryName}"`);
+  }
+  seenQueryNames.add(queryName);
+
+  return new SharedQuery(queryName, fetchFn, options);
+}
+
+const DEFAULT_QUERY_STATE_ENTRY: QueryStateValue<unknown> = {
+  data: null,
+  loading: true,
+  error: null,
+};
+
+/**
+ * React hook to make use of a shared query inside any React component.
+ *
+ *     const users = useQuery(usersQuery, { userId: "123" });
+ */
+export function useQuery<TArgs extends unknown[], TResult>(
+  query: SharedQuery<TArgs, TResult>,
+  args: TArgs,
+): QueryStateValue<TResult> {
+  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);
+
+  // The fetch logic wrapped in useCallback to be stable for useEffect
+  const execute = useCallback(async () => {
+    console.log(`Begin executing shared query ${queryKey}`);
+
+    setQueryState((prev) => {
+      const clone = { ...prev };
+      clone[queryKey] = {
+        data: clone[queryKey]?.data ?? null,
+        loading: true,
+        error: null,
+      };
+      return clone;
+    });
+
+    try {
+      const value = await query.getCachedOrFetch(...args);
+
+      if (isMounted.current) {
+        setQueryState((prev) => {
+          const clone = { ...prev };
+          const now = Date.now();
+          clone[queryKey] = {
+            data: {
+              value,
+              updatedMs: now,
+            },
+            loading: false,
+            error: null,
+          };
+          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 };
+          clone[queryKey] = {
+            data: clone[queryKey]?.data ?? null,
+            loading: false,
+            error,
+          };
+          return clone;
+        });
+      }
+    }
+  }, [queryKey]);
+
+  useEffect(() => {
+    isMounted.current = true;
+
+    void execute();
+
+    return () => {
+      isMounted.current = false;
+    };
+  }, [execute]);
+
+  return (
+    queryState[queryKey] ??
+    (DEFAULT_QUERY_STATE_ENTRY as QueryStateValue<TResult>)
+  );
+}

package/src/sharedState.ts

@@ -1,7 +1,13 @@
-import { kvStore } from "@choksheak/ts-utils/kvStore";
+import { DEFAULT_EXPIRY_DELTA_MS } from "@choksheak/ts-utils/kvStore";
 import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
 import { useSyncExternalStore } from "react";
 
+import {
+  getStorageAdapter,
+  StorageAdapter,
+  StorageOptions,
+} from "./utils/storage";
+
 /**
  * The "shared state" is a React state that shares the same value across the
  * entire app. It is largely similar to the jotai library, but is much smaller
@@ -22,13 +28,13 @@ import { useSyncExternalStore } from "react";
  */
 export class SharedStateConfig {
   /**
-   * Default duration for persistence expiration in milliseconds. Initial value
+   * Default duration for storage expiration in milliseconds. Initial value
    * is 30 days, but can be changed to anything.
    */
-  public static persistExpiryMs = MS_PER_DAY * 30;
+  public static storeExpiryMs = MS_PER_DAY * 30;
 
   /**
-   * True to load from persistence only on mount, false (default) to load in
+   * True to load from storage only on mount, false (default) to load in
    * the top level scope when the shared state is defined.
    */
   public static lazyLoad = false;
@@ -40,11 +46,6 @@ export class SharedStateConfig {
 
 type Subscriber<T> = (next: T, prev: T) => void;
 
-type PersistenceAdapter<T> = {
-  save?: (value: T) => Promise<void> | void;
-  load?: () => Promise<T | undefined> | T | undefined;
-};
-
 class PubSubStore {
   private dataByKey = new Map<string, unknown>();
   private subscribersByKey = new Map<string, Set<Subscriber<unknown>>>();
@@ -65,6 +66,10 @@ class PubSubStore {
     this.notify(key, value, prev);
   }
 
+  public delete(key: string): void {
+    this.dataByKey.delete(key);
+  }
+
   public setNoNotify<T>(key: string, value: T): void {
     this.dataByKey.set(key, value);
   }
@@ -103,95 +108,91 @@ class PubSubStore {
   }
 }
 
-const store = new PubSubStore();
+const pubSubStore = new PubSubStore();
 
-export type SharedState<T> = {
-  subscribe: (subscriber: () => void) => () => void;
-  getSnapshot: () => T;
-  initDefaultValueOnce: () => Promise<void> | void;
-  initDone: boolean;
-  setValue: (next: T | ((prev: T) => T)) => void;
-};
+const STORAGE_KEY = "state";
+
+export type SharedStateOptions<T> = {
+  lazyLoad?: boolean;
+} & StorageOptions<T>;
 
 let stateKey = 0;
 
-/**
- * Create a new shared state object. Put this code at the top level scope:
- *
- *   const myState = sharedState<number>(0);
- */
-export function sharedState<T>(
-  defaultValue: T,
-  options?: {
-    localStorageKey?: string;
-    indexedDbKey?: string;
-    persistExpiryMs?: number;
-    lazyLoad?: boolean;
-  },
-): SharedState<T> {
-  const { localStorageKey, indexedDbKey, persistExpiryMs, lazyLoad } =
-    options ?? {};
+export class SharedState<T> {
+  private readonly pubSubKey: string;
+  private readonly storageAdapter: StorageAdapter<T> | null;
+  public initDone = false;
+
+  public constructor(
+    private readonly defaultValue: T,
+    options?: SharedStateOptions<T>,
+  ) {
+    this.pubSubKey = String(stateKey++);
+
+    // Use max of 1 storage adapter per shared state.
+    this.storageAdapter = getStorageAdapter(options, DEFAULT_EXPIRY_DELTA_MS);
 
-  const key = String(stateKey++);
+    // Always set the default value first to avoid returning undefineds if that
+    // is not part of T.
+    pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
 
-  // Use up to 1 persistence adapter per shared state.
-  let persistenceAdapter: PersistenceAdapter<T> | undefined;
-  const expiryMs = persistExpiryMs ?? SharedStateConfig.persistExpiryMs;
+    const lazyLoad = options?.lazyLoad;
+    const lazy = lazyLoad !== undefined ? lazyLoad : SharedStateConfig.lazyLoad;
 
-  if (localStorageKey) {
-    persistenceAdapter = new LocalStorageAdapter<T>(localStorageKey, expiryMs);
-  } else if (indexedDbKey) {
-    persistenceAdapter = new IndexedDbAdapter<T>(indexedDbKey, expiryMs);
+    if (!lazy) {
+      void this.initDefaultValueOnce();
+    }
   }
 
   // `subscribe` function required by useSyncExternalStore
-  function subscribe(subscriber: () => void): () => void {
-    return store.subscribe(key, () => subscriber());
+  public subscribe(subscriber: () => void): () => void {
+    return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
   }
 
+  // Get the value of the shared state.
   // `getSnapshot` function — must return same ref if value unchanged
-  function getSnapshot(): T {
-    return store.get(key);
+  public getSnapshot(): T {
+    return pubSubStore.get(this.pubSubKey);
   }
 
-  function setValue(next: T | ((prev: T) => T)): void {
+  // Set the value of the shared state.
+  public setValue(next: T | ((prev: T) => T)): void {
     if (typeof next === "function") {
-      const prev = store.get<T>(key);
+      const prev = pubSubStore.get<T>(this.pubSubKey);
       next = (next as (p: T) => T)(prev);
     }
 
-    store.set(key, next);
-    void persistenceAdapter?.save?.(next);
+    pubSubStore.set(this.pubSubKey, next);
+    void this.storageAdapter?.save(STORAGE_KEY, next);
   }
 
-  // Always set the default value first to avoid returning undefineds if that
-  // is not part of T.
-  store.setNoNotify(key, defaultValue);
-
-  const state = {
-    subscribe,
-    getSnapshot,
-
-    // initial default handling
-    initDefaultValueOnce: async () => {
-      if (state.initDone) return;
-      state.initDone = true;
-
-      const v = await persistenceAdapter?.load?.();
-      store.set(key, v !== undefined ? v : defaultValue);
-    },
-    initDone: false,
-
-    setValue,
-  };
+  // Remove the value of the shared state. Actually this just sets the value
+  // back to the given default value.
+  public delete() {
+    pubSubStore.set(this.pubSubKey, this.defaultValue);
+    void this.storageAdapter?.save(STORAGE_KEY, this.defaultValue);
+  }
 
-  const lazy = lazyLoad !== undefined ? lazyLoad : SharedStateConfig.lazyLoad;
+  // Initial default handling
+  public async initDefaultValueOnce() {
+    if (this.initDone) return;
+    this.initDone = true;
 
-  if (!lazy) {
-    void state.initDefaultValueOnce();
+    const v = await this.storageAdapter?.load(STORAGE_KEY);
+    pubSubStore.set(this.pubSubKey, v !== undefined ? v : this.defaultValue);
   }
+}
 
-  return state;
+/**
+ * Create a new shared state object. Put this code at the top level scope:
+ *
+ *   const myState = sharedState<number>(0);
+ */
+export function sharedState<T>(
+  defaultValue: T,
+  options?: SharedStateOptions<T>,
+): SharedState<T> {
+  return new SharedState(defaultValue, options);
 }
 
 /**
@@ -222,67 +223,3 @@ export function useSharedStateValue<T>(state: SharedState<T>) {
 export function useSharedStateSetter<T>(state: SharedState<T>) {
   return useSharedState(state)[1];
 }
-
-/************************************************************************/
-/* Persistence adapters                                                 */
-/************************************************************************/
-
-/** Save state to local storage. */
-type LSBox<T> = { value: T; expiresAt: number };
-
-class LocalStorageAdapter<T> implements PersistenceAdapter<T> {
-  public constructor(
-    public readonly key: string,
-    public readonly expiryMs: number,
-  ) {}
-
-  public save(value: T): void {
-    if (typeof window === "undefined") return;
-
-    window.localStorage.setItem(
-      this.key,
-      JSON.stringify({
-        value,
-        expiresAt: Date.now() + this.expiryMs,
-      } satisfies LSBox<T>),
-    );
-  }
-
-  public load(): T | undefined {
-    if (typeof window === "undefined") return undefined;
-
-    const raw = window.localStorage.getItem(this.key);
-    if (!raw) return undefined;
-
-    const box = JSON.parse(raw) as LSBox<T>;
-    if (!box || !box?.expiresAt || Date.now() >= box.expiresAt) {
-      window.localStorage.removeItem(this.key);
-      return undefined;
-    }
-
-    return box.value;
-  }
-}
-
-/** Save state to indexed db. */
-class IndexedDbAdapter<T> implements PersistenceAdapter<T> {
-  public constructor(
-    public readonly key: string,
-    public readonly expiryMs: number,
-  ) {}
-
-  public async save(value: T): Promise<void> {
-    if (typeof window === "undefined") return;
-
-    await kvStore.set(this.key, JSON.stringify(value), this.expiryMs);
-  }
-
-  public async load(): Promise<T | undefined> {
-    if (typeof window === "undefined") return undefined;
-
-    const raw = await kvStore.get<string>(this.key);
-    if (raw === undefined) return undefined;
-
-    return JSON.parse(raw);
-  }
-}