@choksheak/react-utils 0.1.6 → 0.1.8

package/sharedQuery.mjs

@@ -0,0 +1,444 @@
+// src/sharedQuery.ts
+import { DEFAULT_EXPIRY_DELTA_MS as DEFAULT_EXPIRY_DELTA_MS2 } from "@choksheak/ts-utils/kvStore";
+import { useCallback, useEffect, useRef } from "react";
+
+// 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";
+
+// src/utils/storage.ts
+import { kvStore } from "@choksheak/ts-utils/kvStore";
+function getStorageAdapter(options, defaultStoreExpiryMs) {
+  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
+  if (store) {
+    return store;
+  }
+  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
+  if (localStorageKey) {
+    return new LocalStorageAdapter(localStorageKey, expiryMs);
+  }
+  if (indexedDbKey) {
+    return new IndexedDbAdapter(indexedDbKey, expiryMs);
+  }
+  return null;
+}
+var LocalStorageAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.setItem(
+      fullKey,
+      JSON.stringify({
+        value,
+        expiresAt: this.expiryMs ? Date.now() + this.expiryMs : 0
+      })
+    );
+  }
+  load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = window.localStorage.getItem(fullKey);
+    if (!raw) return void 0;
+    try {
+      const box = JSON.parse(raw);
+      if (!box || box.expiresAt && Date.now() >= box.expiresAt) {
+        window.localStorage.removeItem(fullKey);
+        return void 0;
+      }
+      return box.value;
+    } catch {
+      window.localStorage.removeItem(fullKey);
+      return void 0;
+    }
+  }
+  delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    window.localStorage.removeItem(fullKey);
+  }
+  clear() {
+    if (typeof window === "undefined") return;
+    for (const key of Object.keys(window.localStorage)) {
+      if (key.startsWith(this.keyPrefix)) {
+        window.localStorage.removeItem(key);
+      }
+    }
+  }
+};
+var IndexedDbAdapter = class {
+  constructor(keyPrefix, expiryMs) {
+    this.keyPrefix = keyPrefix;
+    this.expiryMs = expiryMs;
+  }
+  async save(key, value) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
+  }
+  async load(key) {
+    if (typeof window === "undefined") return void 0;
+    const fullKey = this.keyPrefix + ":" + key;
+    const raw = await kvStore.get(fullKey);
+    if (raw === void 0) return void 0;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      await kvStore.delete(fullKey);
+      return void 0;
+    }
+  }
+  async delete(key) {
+    if (typeof window === "undefined") return;
+    const fullKey = this.keyPrefix + ":" + key;
+    await kvStore.delete(fullKey);
+  }
+  async clear() {
+    if (typeof window === "undefined") return;
+    await kvStore.forEach(async (k) => {
+      if (k.startsWith(this.keyPrefix)) {
+        await kvStore.delete(k);
+      }
+    });
+  }
+};
+
+// src/sharedState.ts
+var SharedStateConfig = class {
+  /**
+   * Default duration for storage expiration in milliseconds. Initial value
+   * is 30 days, but can be changed to anything.
+   */
+  static storeExpiryMs = MS_PER_DAY * 30;
+  /**
+   * 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;
+};
+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);
+    if (!subscribers) return;
+    const copy = Array.from(subscribers.values());
+    for (const subscriber of copy) {
+      try {
+        subscriber(next, prev);
+      } catch (e) {
+        console.error(`Error invoking subscriber:`, e);
+      }
+    }
+  }
+};
+var pubSubStore = new PubSubStore();
+var STORAGE_KEY = "state";
+var stateKey = 0;
+var SharedState = class {
+  constructor(defaultValue, options) {
+    this.defaultValue = defaultValue;
+    this.pubSubKey = String(stateKey++);
+    this.storageAdapter = getStorageAdapter(options, DEFAULT_EXPIRY_DELTA_MS);
+    pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
+    const lazyLoad = options?.lazyLoad;
+    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
+    if (!lazy) {
+      void this.initDefaultValueOnce();
+    }
+  }
+  pubSubKey;
+  storageAdapter;
+  initDone = false;
+  // `subscribe` function required by useSyncExternalStore
+  subscribe(subscriber) {
+    return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
+  }
+  // Get the value of the shared state.
+  // `getSnapshot` function — must return same ref if value unchanged
+  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);
+    }
+    pubSubStore.set(this.pubSubKey, next);
+    void this.storageAdapter?.save(STORAGE_KEY, next);
+  }
+  // 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?.save(STORAGE_KEY, this.defaultValue);
+  }
+  // Initial default handling
+  async initDefaultValueOnce() {
+    if (this.initDone) return;
+    this.initDone = true;
+    const v = await this.storageAdapter?.load(STORAGE_KEY);
+    pubSubStore.set(this.pubSubKey, v !== void 0 ? v : this.defaultValue);
+  }
+};
+function sharedState(defaultValue, options) {
+  return new SharedState(defaultValue, options);
+}
+function useSharedState(state) {
+  state.initDefaultValueOnce();
+  const value = useSyncExternalStore(
+    (onStoreChange) => state.subscribe(onStoreChange),
+    () => state.getSnapshot(),
+    // getServerSnapshot is needed to prevent SSR dev errors in nextjs.
+    () => state.getSnapshot()
+  );
+  return [value, state.setValue];
+}
+
+// src/utils/stringify.ts
+function stringifyDeterministicForKeys(params) {
+  const cache = /* @__PURE__ */ new Set();
+  return JSON.stringify(params, (_, value) => {
+    if (typeof value === "function") {
+      throw new Error(`Functions should not be passed into query parameters`);
+    }
+    if (!value || typeof value !== "object") {
+      return value;
+    }
+    if (cache.has(value)) {
+      return "[Circular]";
+    }
+    cache.add(value);
+    if (value !== params) {
+      try {
+        JSON.stringify(value);
+      } catch {
+        return "[Unserializable]";
+      }
+    }
+    return Object.keys(value).sort().reduce(
+      (result, key) => {
+        result[key] = value[key];
+        return result;
+      },
+      {}
+    );
+  });
+}
+
+// src/sharedQuery.ts
+var DEFAULT_STALE_MS = 0;
+var SharedQuery = class {
+  constructor(queryName, fetchFn, options) {
+    this.queryName = queryName;
+    this.fetchFn = fetchFn;
+    this.expiryMs = options?.expiryMs !== void 0 ? options?.expiryMs : DEFAULT_EXPIRY_DELTA_MS2;
+    this.staleMs = options?.staleMs !== void 0 ? options?.staleMs : DEFAULT_STALE_MS;
+    this.revalidateOnStale = Boolean(options?.revalidateOnStale);
+    this.queryState = sharedState(
+      {},
+      {
+        ...options,
+        // Fallback to use expiryMs for the storeExpiryMs.
+        storeExpiryMs: options?.storeExpiryMs || this.expiryMs
+      }
+    );
+  }
+  inflightPromises = /* @__PURE__ */ new Map();
+  queryState;
+  expiryMs;
+  staleMs;
+  revalidateOnStale;
+  getQueryKey(args) {
+    return this.queryName + ":" + stringifyDeterministicForKeys(args);
+  }
+  isStale(entry) {
+    if (this.staleMs === 0) return true;
+    const ageMs = Date.now() - entry.updatedMs;
+    return ageMs > this.staleMs;
+  }
+  isExpired(entry) {
+    if (this.expiryMs === 0) return false;
+    const ageMs = Date.now() - entry.updatedMs;
+    return ageMs > this.expiryMs;
+  }
+  fetchNoCaching(queryKey, ...args) {
+    const inflightPromise = this.inflightPromises.get(queryKey);
+    if (inflightPromise) {
+      console.log(`Deduplicating inflight fetch for ${queryKey}`);
+      return inflightPromise;
+    }
+    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;
+  }
+  async getCachedOrFetch(...args) {
+    const queryKey = this.getQueryKey(args);
+    const cached = this.queryState.getSnapshot()?.[queryKey];
+    if (cached?.data && !this.isExpired(cached.data)) {
+      if (!this.isStale(cached.data)) {
+        console.log(
+          `Return fresh data ${queryKey} from cache without fetching`
+        );
+        return cached.data.value;
+      }
+      if (this.revalidateOnStale) {
+        console.log(`revalidateOnStale for ${queryKey}`);
+        void this.fetchNoCaching(queryKey, ...args);
+      }
+      console.log(`Returning stale data for ${queryKey}`);
+      return cached.data.value;
+    }
+    return await this.fetchNoCaching(queryKey, ...args);
+  }
+  async setCache(queryKey, value) {
+    const entry = {
+      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. */
+  async updateFromSource(...args) {
+    const key = this.getQueryKey(args);
+    return await this.fetchNoCaching(key, ...args);
+  }
+  /** Delete the currently cached data. */
+  invalidate(args) {
+    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. */
+  clearAll() {
+    this.queryState.delete();
+    this.inflightPromises.clear();
+  }
+};
+var seenQueryNames = /* @__PURE__ */ new Set();
+function sharedQuery(queryName, fetchFn, options) {
+  if (seenQueryNames.has(queryName)) {
+    throw new Error(`Duplicate shared query "${queryName}"`);
+  }
+  seenQueryNames.add(queryName);
+  return new SharedQuery(queryName, fetchFn, options);
+}
+var DEFAULT_QUERY_STATE_ENTRY = {
+  data: null,
+  loading: true,
+  error: null
+};
+function useQuery(query, args) {
+  const [queryState, setQueryState] = useSharedState(query.queryState);
+  const isMounted = useRef(true);
+  const queryKey = query.getQueryKey(args);
+  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;
+}
+export {
+  SharedQuery,
+  sharedQuery,
+  useQuery
+};

package/sharedState.d.mts

@@ -1,3 +1,5 @@
+import { StorageOptions } from './utils/storage.mjs';
+
 /**
  * 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
@@ -15,34 +17,37 @@
  */
 declare 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.
      */
-    static persistExpiryMs: number;
+    static storeExpiryMs: number;
     /**
-     * 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.
      */
     static lazyLoad: boolean;
 }
-type SharedState<T> = {
-    subscribe: (subscriber: () => void) => () => void;
-    getSnapshot: () => T;
-    initDefaultValueOnce: () => Promise<void> | void;
+type SharedStateOptions<T> = {
+    lazyLoad?: boolean;
+} & StorageOptions<T>;
+declare class SharedState<T> {
+    private readonly defaultValue;
+    private readonly pubSubKey;
+    private readonly storageAdapter;
     initDone: boolean;
-    setValue: (next: T | ((prev: T) => T)) => void;
-};
+    constructor(defaultValue: T, options?: SharedStateOptions<T>);
+    subscribe(subscriber: () => void): () => void;
+    getSnapshot(): T;
+    setValue(next: T | ((prev: T) => T)): void;
+    delete(): void;
+    initDefaultValueOnce(): Promise<void>;
+}
 /**
  * Create a new shared state object. Put this code at the top level scope:
  *
  *   const myState = sharedState<number>(0);
  */
-declare function sharedState<T>(defaultValue: T, options?: {
-    localStorageKey?: string;
-    indexedDbKey?: string;
-    persistExpiryMs?: number;
-    lazyLoad?: boolean;
-}): SharedState<T>;
+declare function sharedState<T>(defaultValue: T, options?: SharedStateOptions<T>): SharedState<T>;
 /**
  * React hook for subscribing to a key in the global store.
  *   const [my, setMy] = useSharedState(myState);
@@ -53,4 +58,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 { type SharedState, SharedStateConfig, sharedState, useSharedState, useSharedStateSetter, useSharedStateValue };
+export { SharedState, SharedStateConfig, type SharedStateOptions, sharedState, useSharedState, useSharedStateSetter, useSharedStateValue };

package/sharedState.d.ts

@@ -1,3 +1,4 @@
+import { 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
@@ -15,34 +16,37 @@
  */
 export declare 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.
      */
-    static persistExpiryMs: number;
+    static storeExpiryMs: number;
     /**
-     * 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.
      */
     static lazyLoad: boolean;
 }
-export type SharedState<T> = {
-    subscribe: (subscriber: () => void) => () => void;
-    getSnapshot: () => T;
-    initDefaultValueOnce: () => Promise<void> | void;
+export type SharedStateOptions<T> = {
+    lazyLoad?: boolean;
+} & StorageOptions<T>;
+export declare class SharedState<T> {
+    private readonly defaultValue;
+    private readonly pubSubKey;
+    private readonly storageAdapter;
     initDone: boolean;
-    setValue: (next: T | ((prev: T) => T)) => void;
-};
+    constructor(defaultValue: T, options?: SharedStateOptions<T>);
+    subscribe(subscriber: () => void): () => void;
+    getSnapshot(): T;
+    setValue(next: T | ((prev: T) => T)): void;
+    delete(): void;
+    initDefaultValueOnce(): Promise<void>;
+}
 /**
  * Create a new shared state object. Put this code at the top level scope:
  *
  *   const myState = sharedState<number>(0);
  */
-export declare function sharedState<T>(defaultValue: T, options?: {
-    localStorageKey?: string;
-    indexedDbKey?: string;
-    persistExpiryMs?: number;
-    lazyLoad?: boolean;
-}): SharedState<T>;
+export declare function sharedState<T>(defaultValue: T, options?: SharedStateOptions<T>): SharedState<T>;
 /**
  * React hook for subscribing to a key in the global store.
  *   const [my, setMy] = useSharedState(myState);