@choksheak/react-utils 0.2.4 → 0.2.6

package/src/sharedState.ts

@@ -1,232 +0,0 @@
-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
- * and much easier to work with when used for persisting in local storage or
- * indexed db, with an automatic expiration for persisted values.
- *
- * This library aims to be the shortest, simplest, easiest to use, and most
- * efficient implementation of shared global React states with seamless support
- * for client persistence.
- */
-
-/************************************************************************/
-/* Global config                                                        */
-/************************************************************************/
-
-/**
- * These values are configurable by the user at any time.
- */
-export const SharedStateDefaults = {
-  /**
-   * Default duration for storage expiration in milliseconds. Initial value
-   * is 30 days, but can be changed to anything.
-   */
-  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.
-   */
-  lazyLoad: false,
-};
-
-/************************************************************************/
-/* Shared state implementation                                          */
-/************************************************************************/
-
-type Subscriber<T> = (next: T, prev: T) => void;
-
-class PubSubStore {
-  private dataByKey = new Map<string, unknown>();
-  private subscribersByKey = new Map<string, Set<Subscriber<unknown>>>();
-
-  // This could be undefined if T includes undefined, else it should never
-  // return undefined because the user has to always specify the default value.
-  public get<T>(key: string): T {
-    return this.dataByKey.get(key) as T;
-  }
-
-  public set<T>(key: string, value: T): void {
-    const prev = this.dataByKey.get(key) as T;
-
-    // Do nothing if no change.
-    if (prev === value) return;
-
-    this.dataByKey.set(key, value);
-    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);
-  }
-
-  // Subscribe to changes of a specific key
-  public subscribe<T>(key: string, subscriber: Subscriber<T>): () => void {
-    let subscribers = this.subscribersByKey.get(key);
-    if (!subscribers) {
-      subscribers = new Set();
-      this.subscribersByKey.set(key, subscribers);
-    }
-
-    // Type coercion: we store Subscriber<unknown>
-    subscribers.add(subscriber as Subscriber<unknown>);
-
-    // Return unsubscribe function
-    return () => {
-      subscribers.delete(subscriber as Subscriber<unknown>);
-      if (subscribers.size === 0) this.subscribersByKey.delete(key);
-    };
-  }
-
-  private notify<T>(key: string, next: T, prev: T): void {
-    const subscribers = this.subscribersByKey.get(key);
-    if (!subscribers) return;
-
-    // Make copy to protect against mutation during iteration.
-    const copy = Array.from(subscribers.values());
-    for (const subscriber of copy) {
-      try {
-        subscriber(next, prev);
-      } catch (e) {
-        console.error(`Error invoking subscriber:`, e);
-      }
-    }
-  }
-}
-
-const pubSubStore = new PubSubStore();
-
-const STORAGE_KEY = "state";
-
-export type SharedStateOptions<T> = {
-  lazyLoad?: boolean;
-} & StorageOptions<T>;
-
-let stateKey = 0;
-
-export class SharedState<T> {
-  private readonly pubSubKey: string;
-  private readonly storageAdapter: StorageAdapter<T> | null;
-  public readonly setValueBounded: (next: T | ((prev: T) => T)) => void;
-  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,
-      SharedStateDefaults.storeExpiryMs,
-    );
-
-    // Same as this.setValue, but binding the `this` reference.
-    this.setValueBounded = (arg) => this.setValue(arg);
-
-    // Always set the default value first to avoid returning undefineds if that
-    // is not part of T.
-    pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
-
-    const lazyLoad = options?.lazyLoad;
-    const lazy =
-      lazyLoad !== undefined ? lazyLoad : SharedStateDefaults.lazyLoad;
-
-    if (!lazy) {
-      void this.initDefaultValueOnce();
-    }
-  }
-
-  // `subscribe` function required by useSyncExternalStore
-  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
-  public getSnapshot(): T {
-    return pubSubStore.get(this.pubSubKey);
-  }
-
-  // Set the value of the shared state.
-  public setValue(next: T | ((prev: T) => T)): void {
-    if (typeof next === "function") {
-      const prev = pubSubStore.get<T>(this.pubSubKey);
-      next = (next as (p: T) => T)(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.
-  public delete() {
-    pubSubStore.set(this.pubSubKey, this.defaultValue);
-    void this.storageAdapter?.save(STORAGE_KEY, this.defaultValue);
-  }
-
-  // Initial default handling
-  public async initDefaultValueOnce() {
-    if (this.initDone) return;
-    this.initDone = true;
-
-    const v = await this.storageAdapter?.load(STORAGE_KEY);
-    pubSubStore.set(this.pubSubKey, v !== undefined ? v : this.defaultValue);
-  }
-}
-
-/**
- * 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);
-}
-
-/**
- * React hook for subscribing to a key in the global store.
- *   const [my, setMy] = useSharedState(myState);
- */
-export function useSharedState<T>(
-  state: SharedState<T>,
-): [T, (next: T | ((prev: T) => T)) => 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];
-}
-
-/** E.g. const my = useSharedStateValue(myState) */
-export function useSharedStateValue<T>(state: SharedState<T>) {
-  return useSharedState(state)[0];
-}
-
-/** E.g. const setMy = useSharedStateSetter(myState) */
-export function useSharedStateSetter<T>(state: SharedState<T>) {
-  return useSharedState(state)[1];
-}

package/src/utils/storage.ts

@@ -1,197 +0,0 @@
-import { kvStore } from "@choksheak/ts-utils/kvStore";
-
-export type StorageAdapter<T> = {
-  save: (key: string, value: T) => Promise<void> | void;
-  load: (key: string) => Promise<T | undefined> | T | undefined;
-  delete: (key: string) => Promise<void> | void;
-  clear: () => Promise<void> | void;
-};
-
-export type StorageOptions<T> = {
-  // If specified, this will be used and all other fields will be ignored.
-  store?: StorageAdapter<T>;
-
-  // Storage key in local storage for this data.
-  localStorageKey?: string;
-
-  // Storage key in indexed db for this data.
-  indexedDbKey?: string;
-
-  // How long to wait before the value is considered expired.
-  storeExpiryMs?: number;
-};
-
-export function getStorageAdapter<T>(
-  options: StorageOptions<T> | undefined,
-  defaultStoreExpiryMs: number,
-): StorageAdapter<T> | null {
-  const { localStorageKey, indexedDbKey, storeExpiryMs, store } = options ?? {};
-
-  if (store) {
-    return store;
-  }
-
-  const expiryMs = storeExpiryMs || defaultStoreExpiryMs;
-
-  if (localStorageKey) {
-    return new LocalStorageAdapter<T>(localStorageKey, expiryMs);
-  }
-
-  if (indexedDbKey) {
-    return new IndexedDbAdapter<T>(indexedDbKey, expiryMs);
-  }
-
-  return null;
-}
-
-/************************************************************************/
-/* Storage adapters                                                     */
-/************************************************************************/
-
-type ValueWithExpiration<T> = { value: T; expiresAt: number };
-
-/** Save state to memory only - not persisted. */
-export class InMemoryStorageAdapter<T> implements StorageAdapter<T> {
-  private readonly cache = new Map<string, ValueWithExpiration<T>>();
-
-  public constructor(
-    public readonly keyPrefix: string,
-    public readonly expiryMs: number,
-  ) {}
-
-  public save(key: string, value: T): void {
-    const fullKey = this.keyPrefix + ":" + key;
-    this.cache.set(fullKey, {
-      value,
-      expiresAt: Date.now() + this.expiryMs,
-    });
-  }
-
-  public load(key: string): T | undefined {
-    const fullKey = this.keyPrefix + ":" + key;
-    const cached = this.cache.get(fullKey);
-
-    if (cached && Date.now() < cached.expiresAt) {
-      return cached.value;
-    }
-
-    return undefined;
-  }
-
-  public delete(key: string): void {
-    const fullKey = this.keyPrefix + ":" + key;
-    this.cache.delete(fullKey);
-  }
-
-  public clear(): void {
-    this.cache.clear();
-  }
-}
-
-/** Save state to local storage. */
-export class LocalStorageAdapter<T> implements StorageAdapter<T> {
-  public constructor(
-    public readonly keyPrefix: string,
-    public readonly expiryMs: number,
-  ) {}
-
-  public save(key: string, value: T): void {
-    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,
-      } satisfies ValueWithExpiration<T>),
-    );
-  }
-
-  public load(key: string): T | undefined {
-    if (typeof window === "undefined") return undefined;
-
-    const fullKey = this.keyPrefix + ":" + key;
-    const raw = window.localStorage.getItem(fullKey);
-    if (!raw) return undefined;
-
-    try {
-      const box = JSON.parse(raw) as ValueWithExpiration<T>;
-      if (!box || (box.expiresAt && Date.now() >= box.expiresAt)) {
-        window.localStorage.removeItem(fullKey);
-        return undefined;
-      }
-
-      return box.value;
-    } catch {
-      // Ignore error.
-      window.localStorage.removeItem(fullKey);
-      return undefined;
-    }
-  }
-
-  public delete(key: string): void {
-    if (typeof window === "undefined") return;
-
-    const fullKey = this.keyPrefix + ":" + key;
-    window.localStorage.removeItem(fullKey);
-  }
-
-  public clear(): void {
-    if (typeof window === "undefined") return;
-
-    for (const key of Object.keys(window.localStorage)) {
-      if (key.startsWith(this.keyPrefix)) {
-        window.localStorage.removeItem(key);
-      }
-    }
-  }
-}
-
-/** Save state to indexed db. */
-export class IndexedDbAdapter<T> implements StorageAdapter<T> {
-  public constructor(
-    public readonly keyPrefix: string,
-    public readonly expiryMs: number,
-  ) {}
-
-  public async save(key: string, value: T): Promise<void> {
-    if (typeof window === "undefined") return;
-
-    const fullKey = this.keyPrefix + ":" + key;
-    await kvStore.set(fullKey, JSON.stringify(value), this.expiryMs);
-  }
-
-  public async load(key: string): Promise<T | undefined> {
-    if (typeof window === "undefined") return undefined;
-
-    const fullKey = this.keyPrefix + ":" + key;
-    const raw = await kvStore.get<string>(fullKey);
-    if (raw === undefined) return undefined;
-
-    try {
-      return JSON.parse(raw);
-    } catch {
-      // Ignore error.
-      await kvStore.delete(fullKey);
-      return undefined;
-    }
-  }
-
-  public async delete(key: string): Promise<void> {
-    if (typeof window === "undefined") return;
-
-    const fullKey = this.keyPrefix + ":" + key;
-    await kvStore.delete(fullKey);
-  }
-
-  public async clear(): Promise<void> {
-    if (typeof window === "undefined") return;
-
-    await kvStore.forEach(async (k) => {
-      if (k.startsWith(this.keyPrefix)) {
-        await kvStore.delete(k);
-      }
-    });
-  }
-}

package/src/utils/stringify.ts

@@ -1,49 +0,0 @@
-/**
- * JSON stringify a value of any type, and returns an unsafe string. The string
- * is "unsafe" because you might not be able to restore the original object
- * using the serialized JSON. This is specifically used for query key generation
- * and is not suitable for more general uses.
- *
- * Note: The given value should not contain any functions because functions
- * cannot be serialized and deserialized properly.
- */
-export function stringifyDeterministicForKeys(params: unknown): string {
-  const cache = 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" || Array.isArray(value)) {
-      return value;
-    }
-
-    if (cache.has(value)) {
-      // Circular reference detected! Return a placeholder string.
-      return "[Circular]";
-    }
-
-    cache.add(value);
-
-    // Don't crash on circular references, but don't mark the top level object
-    // as circular because we want to return as much string as possible.
-    if (value !== params) {
-      try {
-        JSON.stringify(value);
-      } catch {
-        return "[Unserializable]";
-      }
-    }
-
-    return Object.keys(value)
-      .sort()
-      .reduce(
-        (result: Record<string, unknown>, key: string) => {
-          result[key] = value[key];
-          return result;
-        },
-        {} as Record<string, unknown>,
-      );
-  });
-}

package/src/utils/useDeepMemo.ts

@@ -1,19 +0,0 @@
-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]);
-}