@choksheak/react-utils 0.1.9 → 0.2.1

package/sharedState.d.mts

@@ -15,18 +15,18 @@ import { StorageOptions } from './utils/storage.mjs';
 /**
  * These values are configurable by the user at any time.
  */
-declare class SharedStateConfig {
+declare const SharedStateDefaults: {
     /**
      * Default duration for storage expiration in milliseconds. Initial value
      * is 30 days, but can be changed to anything.
      */
-    static storeExpiryMs: number;
+    storeExpiryMs: number;
     /**
      * True to load from storage only on mount, false (default) to load in
      * the top level scope when the shared state is defined.
      */
-    static lazyLoad: boolean;
-}
+    lazyLoad: boolean;
+};
 type SharedStateOptions<T> = {
     lazyLoad?: boolean;
 } & StorageOptions<T>;
@@ -59,4 +59,4 @@ declare function useSharedStateValue<T>(state: SharedState<T>): T;
 /** E.g. const setMy = useSharedStateSetter(myState) */
 declare function useSharedStateSetter<T>(state: SharedState<T>): (next: T | ((prev: T) => T)) => void;
 
-export { SharedState, SharedStateConfig, type SharedStateOptions, sharedState, useSharedState, useSharedStateSetter, useSharedStateValue };
+export { SharedState, SharedStateDefaults, type SharedStateOptions, sharedState, useSharedState, useSharedStateSetter, useSharedStateValue };

package/sharedState.d.ts

@@ -14,18 +14,18 @@ import { StorageOptions } from "./utils/storage";
 /**
  * These values are configurable by the user at any time.
  */
-export declare class SharedStateConfig {
+export declare const SharedStateDefaults: {
     /**
      * Default duration for storage expiration in milliseconds. Initial value
      * is 30 days, but can be changed to anything.
      */
-    static storeExpiryMs: number;
+    storeExpiryMs: number;
     /**
      * True to load from storage only on mount, false (default) to load in
      * the top level scope when the shared state is defined.
      */
-    static lazyLoad: boolean;
-}
+    lazyLoad: boolean;
+};
 export type SharedStateOptions<T> = {
     lazyLoad?: boolean;
 } & StorageOptions<T>;

package/sharedState.js

@@ -21,14 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var sharedState_exports = {};
 __export(sharedState_exports, {
   SharedState: () => SharedState,
-  SharedStateConfig: () => SharedStateConfig,
+  SharedStateDefaults: () => SharedStateDefaults,
   sharedState: () => sharedState,
   useSharedState: () => useSharedState,
   useSharedStateSetter: () => useSharedStateSetter,
   useSharedStateValue: () => useSharedStateValue
 });
 module.exports = __toCommonJS(sharedState_exports);
-var import_kvStore2 = require("@choksheak/ts-utils/kvStore");
 var import_timeConstants = require("@choksheak/ts-utils/timeConstants");
 var import_react = require("react");
 
@@ -133,17 +132,17 @@ var IndexedDbAdapter = class {
 };
 
 // src/sharedState.ts
-var SharedStateConfig = class {
+var SharedStateDefaults = {
   /**
    * Default duration for storage expiration in milliseconds. Initial value
    * is 30 days, but can be changed to anything.
    */
-  static storeExpiryMs = import_timeConstants.MS_PER_DAY * 30;
+  storeExpiryMs: 30 * import_timeConstants.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.
    */
-  static lazyLoad = false;
+  lazyLoad: false
 };
 var PubSubStore = class {
   dataByKey = /* @__PURE__ */ new Map();
@@ -198,11 +197,14 @@ var SharedState = class {
   constructor(defaultValue, options) {
     this.defaultValue = defaultValue;
     this.pubSubKey = String(stateKey++);
-    this.storageAdapter = getStorageAdapter(options, import_kvStore2.DEFAULT_EXPIRY_DELTA_MS);
+    this.storageAdapter = getStorageAdapter(
+      options,
+      SharedStateDefaults.storeExpiryMs
+    );
     this.setValueBounded = (arg) => this.setValue(arg);
     pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
     const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
+    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateDefaults.lazyLoad;
     if (!lazy) {
       void this.initDefaultValueOnce();
     }
@@ -265,7 +267,7 @@ function useSharedStateSetter(state) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SharedState,
-  SharedStateConfig,
+  SharedStateDefaults,
   sharedState,
   useSharedState,
   useSharedStateSetter,

package/sharedState.mjs

@@ -1,5 +1,4 @@
 // src/sharedState.ts
-import { DEFAULT_EXPIRY_DELTA_MS } from "@choksheak/ts-utils/kvStore";
 import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
 import { useSyncExternalStore } from "react";
 
@@ -104,17 +103,17 @@ var IndexedDbAdapter = class {
 };
 
 // src/sharedState.ts
-var SharedStateConfig = class {
+var SharedStateDefaults = {
   /**
    * Default duration for storage expiration in milliseconds. Initial value
    * is 30 days, but can be changed to anything.
    */
-  static storeExpiryMs = MS_PER_DAY * 30;
+  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.
    */
-  static lazyLoad = false;
+  lazyLoad: false
 };
 var PubSubStore = class {
   dataByKey = /* @__PURE__ */ new Map();
@@ -169,11 +168,14 @@ var SharedState = class {
   constructor(defaultValue, options) {
     this.defaultValue = defaultValue;
     this.pubSubKey = String(stateKey++);
-    this.storageAdapter = getStorageAdapter(options, DEFAULT_EXPIRY_DELTA_MS);
+    this.storageAdapter = getStorageAdapter(
+      options,
+      SharedStateDefaults.storeExpiryMs
+    );
     this.setValueBounded = (arg) => this.setValue(arg);
     pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
     const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
+    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateDefaults.lazyLoad;
     if (!lazy) {
       void this.initDefaultValueOnce();
     }
@@ -235,7 +237,7 @@ function useSharedStateSetter(state) {
 }
 export {
   SharedState,
-  SharedStateConfig,
+  SharedStateDefaults,
   sharedState,
   useSharedState,
   useSharedStateSetter,

package/src/sharedQuery.ts

@@ -1,68 +1,107 @@
-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 { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+import {
+  SharedState,
+  sharedState,
+  SharedStateOptions,
+  useSharedState,
+} from "./sharedState";
 import { stringifyDeterministicForKeys } from "./utils/stringify";
 
-export type FetchFn<TArgs extends unknown[], TResult> = (
+export type FetchFn<TArgs extends unknown[], TData> = (
   ...args: TArgs
-) => Promise<TResult>;
+) => Promise<TData> | TData;
 
-export type FetchedData<TResult> = {
-  value: TResult;
-  updatedMs: number;
+export type QueryStateValue<TData> = {
+  loading: boolean;
+  data?: TData;
+  dataUpdatedMs?: number;
+  error?: Error;
+  errorUpdatedMs?: number;
 };
 
-export type QueryStateValue<TResult> = {
-  data: FetchedData<TResult> | null;
-  loading: boolean;
-  error: Error | null;
+export type UseQueryResult<TData> = QueryStateValue<TData> & {
+  refetch: () => Promise<TData>;
+  setData: (data: TData, dataUpdatedMs?: number) => void;
+  deleteData: () => void;
 };
 
+export type PersistTo = "localStorage" | "indexedDb";
+
 /**
- * The full query state is a record of all the fetch results mapped by
+ * The full query state is a record of all the fetch states mapped by
  * query key to the state entry.
  */
-export type SharedQueryState<TResult> = Record<
-  string,
-  QueryStateValue<TResult>
->;
+export type SharedQueryState<TData> = Record<string, QueryStateValue<TData>>;
+
+export type SharedQueryOptions<TArgs extends unknown[], TData> = {
+  // 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;
+
+  // Function to fetch data.
+  queryFn: FetchFn<TArgs, TData>;
 
-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>>;
+  refetchOnStale?: boolean;
+
+  // Shortcut to set the localStorageKey or indexedDbKey automatically from
+  // queryName. This is important because it avoids requiring the user to
+  // specify the same queryName twice everytime.
+  persistTo?: PersistTo;
+} & SharedStateOptions<SharedQueryState<TData>>;
+
+/** Users can override these values globally. */
+export const SharedQueryDefaults = {
+  staleMs: 0,
+  expiryMs: 30 * MS_PER_DAY,
+  persistTo: undefined as PersistTo | undefined,
+};
 
-const DEFAULT_STALE_MS = 0;
+export class SharedQuery<TArgs extends unknown[], TData> {
+  private readonly inflightPromises = new Map<string, Promise<TData>>();
+  public readonly queryState: SharedState<SharedQueryState<TData>>;
 
-export class SharedQuery<TArgs extends unknown[], TResult> {
-  private readonly inflightPromises = new Map<string, Promise<TResult>>();
-  public readonly queryState: SharedState<SharedQueryState<TResult>>;
+  public readonly queryName: string;
+  private readonly queryFn: FetchFn<TArgs, TData>;
   public readonly expiryMs: number;
   public readonly staleMs: number;
-  public readonly revalidateOnStale: boolean;
+  public readonly refetchOnStale: boolean;
+
+  public constructor(options: SharedQueryOptions<TArgs, TData>) {
+    this.queryName = options.queryName;
+
+    this.queryFn = options.queryFn;
 
-  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;
+        : SharedQueryDefaults.expiryMs;
 
     this.staleMs =
-      options?.staleMs !== undefined ? options?.staleMs : DEFAULT_STALE_MS;
+      options?.staleMs !== undefined
+        ? options?.staleMs
+        : SharedQueryDefaults.staleMs;
+
+    this.refetchOnStale = Boolean(options?.refetchOnStale);
 
-    this.revalidateOnStale = Boolean(options?.revalidateOnStale);
+    // 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;
+    }
 
-    this.queryState = sharedState<SharedQueryState<TResult>>(
+    this.queryState = sharedState<SharedQueryState<TData>>(
       {},
       {
         ...options,
@@ -76,21 +115,48 @@ export class SharedQuery<TArgs extends unknown[], TResult> {
     return this.queryName + ":" + stringifyDeterministicForKeys(args);
   }
 
-  private isStale(entry: FetchedData<TResult>): boolean {
+  private isStale(dataUpdatedMs: number): boolean {
     if (this.staleMs === 0) return true; // always stale
 
-    const ageMs = Date.now() - entry.updatedMs;
+    const ageMs = Date.now() - dataUpdatedMs;
     return ageMs > this.staleMs;
   }
 
-  private isExpired(entry: FetchedData<TResult>): boolean {
+  private isExpired(dataUpdatedMs: number): boolean {
     if (this.expiryMs === 0) return false; // never expire
 
-    const ageMs = Date.now() - entry.updatedMs;
+    const ageMs = Date.now() - dataUpdatedMs;
     return ageMs > this.expiryMs;
   }
 
-  private fetchNoCaching(queryKey: string, ...args: TArgs): Promise<TResult> {
+  public async getCachedOrFetch(...args: TArgs): Promise<TData> {
+    const queryKey = this.getQueryKey(args);
+    const cached = this.queryState.getSnapshot()?.[queryKey];
+
+    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`,
+        );
+        return cached.data;
+      }
+
+      // If stale, optionally update the data in the background.
+      if (this.refetchOnStale) {
+        console.log(`refetchOnStale for ${queryKey}`);
+        void this.dedupedFetch(queryKey, ...args);
+      }
+
+      // Still return stale data immediately.
+      console.log(`Returning stale data for ${queryKey}`);
+      return cached.data;
+    }
+
+    return await this.dedupedFetch(queryKey, ...args);
+  }
+
+  private dedupedFetch(queryKey: string, ...args: TArgs): Promise<TData> {
     const inflightPromise = this.inflightPromises.get(queryKey);
 
     // De-duplicate in-flight requests
@@ -100,87 +166,64 @@ export class SharedQuery<TArgs extends unknown[], TResult> {
     }
 
     // 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);
-      });
+    const promise = this.startFetching(queryKey, args);
 
     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;
-      }
+  private async startFetching(queryKey: string, args: TArgs) {
+    console.log(`Start fetching ${queryKey}`);
 
-      // If stale, optionally update the data in the background.
-      if (this.revalidateOnStale) {
-        console.log(`revalidateOnStale for ${queryKey}`);
-        void this.fetchNoCaching(queryKey, ...args);
-      }
+    try {
+      const data = await this.queryFn(...args);
 
-      // Still return stale data immediately.
-      console.log(`Returning stale data for ${queryKey}`);
-      return cached.data.value;
+      console.log(`Successfully fetched ${queryKey}`);
+      this.setData(queryKey, data, Date.now());
+      return data;
+    } catch (e) {
+      console.error(`Failed to fetch ${queryKey}: ${e}`);
+      throw e;
+    } finally {
+      this.inflightPromises.delete(queryKey);
     }
-
-    return await this.fetchNoCaching(queryKey, ...args);
   }
 
-  private async setCache(queryKey: string, value: TResult): Promise<void> {
-    const entry: QueryStateValue<TResult> = {
-      data: { value, updatedMs: Date.now() },
+  /** Set the data directly if the user obtained it from somewhere else. */
+  public async setData(
+    queryKey: string,
+    data: TData,
+    dataUpdatedMs = Date.now(),
+  ): Promise<void> {
+    const entry: QueryStateValue<TData> = {
       loading: false,
-      error: null,
+      data,
+      dataUpdatedMs,
     };
 
     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> {
+  public async updateFromSource(...args: TArgs): Promise<TData> {
     const key = this.getQueryKey(args);
-    return await this.fetchNoCaching(key, ...args);
+    return await this.dedupedFetch(key, ...args);
   }
 
-  /** Delete the currently cached data. */
-  public invalidate(args?: TArgs): void {
-    if (args) {
-      const queryKey = this.getQueryKey(args);
+  /** Delete the cached data for one set of arguments. */
+  public deleteData(args: TArgs): void {
+    const queryKey = this.getQueryKey(args);
 
-      const record = this.queryState.getSnapshot();
-      const clone = { ...record };
-      delete clone[queryKey];
-      this.queryState.setValue(clone);
+    const record = this.queryState.getSnapshot();
+    const clone = { ...record };
+    delete clone[queryKey];
+    this.queryState.setValue(clone);
 
-      this.inflightPromises.delete(queryKey);
-    } else {
-      this.clearAll();
-    }
+    this.inflightPromises.delete(queryKey);
   }
 
-  /** Delete the currently cached data & all inflight promises. */
-  public clearAll(): void {
+  /** Delete all currently cached data & all inflight promises. */
+  public clear(): void {
     this.queryState.delete();
     this.inflightPromises.clear();
   }
@@ -195,36 +238,31 @@ const seenQueryNames = new Set<string>();
  * 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>(
+export function sharedQuery<TArgs extends unknown[], TData>(
   // 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}"`);
+  options: SharedQueryOptions<TArgs, TData>,
+): SharedQuery<TArgs, TData> {
+  if (seenQueryNames.has(options.queryName)) {
+    throw new Error(`Duplicate shared query "${options.queryName}"`);
   }
-  seenQueryNames.add(queryName);
+  seenQueryNames.add(options.queryName);
 
-  return new SharedQuery(queryName, fetchFn, options);
+  return new SharedQuery(options);
 }
 
-const DEFAULT_QUERY_STATE_ENTRY: QueryStateValue<unknown> = {
-  data: null,
-  loading: true,
-  error: null,
-};
+const DEFAULT_QUERY_STATE_ENTRY: QueryStateValue<unknown> = { loading: true };
 
 /**
  * React hook to make use of a shared query inside any React component.
  *
- *     const users = useQuery(usersQuery, { userId: "123" });
+ *     const users = useSharedQuery(usersQuery, ["123"]);
  */
-export function useQuery<TArgs extends unknown[], TResult>(
-  query: SharedQuery<TArgs, TResult>,
-  args: TArgs,
-): QueryStateValue<TResult> {
+export function useSharedQuery<TArgs extends unknown[], TData>(
+  query: SharedQuery<TArgs, TData>,
+  // Default to use no arguments.
+  args: TArgs = [] as unknown as TArgs,
+): UseQueryResult<TData> {
   const [queryState, setQueryState] = useSharedState(query.queryState);
 
   const isMounted = useRef(true);
@@ -241,27 +279,23 @@ export function useQuery<TArgs extends unknown[], TResult>(
     setQueryState((prev) => {
       const clone = { ...prev };
       clone[queryKey] = {
-        data: clone[queryKey]?.data ?? null,
+        ...(clone[queryKey] ?? {}),
         loading: true,
-        error: null,
       };
       return clone;
     });
 
     try {
-      const value = await query.getCachedOrFetch(...args);
+      const data = await query.getCachedOrFetch(...args);
 
       if (isMounted.current) {
         setQueryState((prev) => {
           const clone = { ...prev };
-          const now = Date.now();
           clone[queryKey] = {
-            data: {
-              value,
-              updatedMs: now,
-            },
+            // Don't keep old error.
             loading: false,
-            error: null,
+            data,
+            dataUpdatedMs: Date.now(),
           };
           return clone;
         });
@@ -276,9 +310,11 @@ export function useQuery<TArgs extends unknown[], TResult>(
         setQueryState((prev) => {
           const clone = { ...prev };
           clone[queryKey] = {
-            data: clone[queryKey]?.data ?? null,
+            // Keep old data.
+            ...(clone[queryKey] ?? {}),
             loading: false,
             error,
+            errorUpdatedMs: Date.now(),
           };
           return clone;
         });
@@ -296,8 +332,22 @@ export function useQuery<TArgs extends unknown[], TResult>(
     };
   }, [execute]);
 
-  return (
-    queryState[queryKey] ??
-    (DEFAULT_QUERY_STATE_ENTRY as QueryStateValue<TResult>)
-  );
+  return useMemo(() => {
+    const state =
+      queryState[queryKey] ??
+      (DEFAULT_QUERY_STATE_ENTRY as QueryStateValue<TData>);
+
+    return {
+      ...state,
+      refetch: () => {
+        return query.updateFromSource(...args);
+      },
+      setData: (data: TData, dataUpdatedMs?: number) => {
+        query.setData(queryKey, data, dataUpdatedMs ?? Date.now());
+      },
+      deleteData: () => {
+        query.deleteData(args);
+      },
+    };
+  }, [query, queryKey, queryState]);
 }

package/src/sharedState.ts

@@ -1,4 +1,3 @@
-import { DEFAULT_EXPIRY_DELTA_MS } from "@choksheak/ts-utils/kvStore";
 import { MS_PER_DAY } from "@choksheak/ts-utils/timeConstants";
 import { useSyncExternalStore } from "react";
 
@@ -26,19 +25,19 @@ import {
 /**
  * These values are configurable by the user at any time.
  */
-export class SharedStateConfig {
+export const SharedStateDefaults = {
   /**
    * Default duration for storage expiration in milliseconds. Initial value
    * is 30 days, but can be changed to anything.
    */
-  public static storeExpiryMs = MS_PER_DAY * 30;
+  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.
    */
-  public static lazyLoad = false;
-}
+  lazyLoad: false,
+};
 
 /************************************************************************/
 /* Shared state implementation                                          */
@@ -131,7 +130,10 @@ export class SharedState<T> {
     this.pubSubKey = String(stateKey++);
 
     // Use max of 1 storage adapter per shared state.
-    this.storageAdapter = getStorageAdapter(options, DEFAULT_EXPIRY_DELTA_MS);
+    this.storageAdapter = getStorageAdapter(
+      options,
+      SharedStateDefaults.storeExpiryMs,
+    );
 
     // Same as this.setValue, but binding the `this` reference.
     this.setValueBounded = (arg) => this.setValue(arg);
@@ -141,7 +143,8 @@ export class SharedState<T> {
     pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
 
     const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== undefined ? lazyLoad : SharedStateConfig.lazyLoad;
+    const lazy =
+      lazyLoad !== undefined ? lazyLoad : SharedStateDefaults.lazyLoad;
 
     if (!lazy) {
       void this.initDefaultValueOnce();