@choksheak/react-utils 0.3.5 → 0.3.7

package/sharedState.mjs

@@ -4,7 +4,7 @@ import { useSyncExternalStore } from "react";
 
 // src/storage.ts
 import { kvStore } from "@choksheak/ts-utils/kvStore";
-import { LocalStore } from "@choksheak/ts-utils/localStore";
+import { createLocalStore } from "@choksheak/ts-utils/localStore";
 var IS_NOT_BROWSER = typeof window === "undefined";
 function getStorageAdapter(options, defaultStoreExpiryMs) {
   const { store } = options ?? {};
@@ -13,70 +13,12 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
     const expiryMs = store.expiryMs || defaultStoreExpiryMs;
-    const isValid = store.isValid;
+    const config = { ...store, expiryMs };
     switch (store.persistTo) {
-      case "localStorage": {
-        const adapter = new LocalStore(store.key, {
-          defaultExpiryMs: expiryMs
-        });
-        return {
-          set: (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.set(key, value);
-          },
-          get: (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const value = adapter.get(key);
-            if (isValid && !isValid(value)) {
-              console.warn(
-                `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              adapter.delete(key);
-              return void 0;
-            }
-            return value;
-          },
-          delete: (key) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.delete(key);
-          },
-          clear: () => {
-            if (IS_NOT_BROWSER) return;
-            adapter.clear();
-          }
-        };
-      }
-      case "indexedDb": {
-        const keyPrefix = store.key + ":";
-        const isValid2 = store.isValid;
-        return {
-          set: async (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.set(keyPrefix + key, value, expiryMs);
-          },
-          get: async (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const fullKey = keyPrefix + key;
-            const value = await kvStore.get(fullKey);
-            if (isValid2 && !isValid2(value)) {
-              console.warn(
-                `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              await kvStore.delete(fullKey);
-              return void 0;
-            }
-            return value;
-          },
-          delete: async (key) => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.delete(keyPrefix + key);
-          },
-          clear: async () => {
-            if (IS_NOT_BROWSER) return;
-            await kvStore.clear();
-          }
-        };
-      }
+      case "localStorage":
+        return localStoreAdapter(config);
+      case "indexedDb":
+        return kvStoreAdapter(config);
       default:
         store.persistTo;
         throw new Error(`Unknown store.adapter ${store.persistTo}`);
@@ -84,6 +26,73 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   return store;
 }
+function localStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const adapter = createLocalStore(key, { defaultExpiryMs: expiryMs });
+  return {
+    set: (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.set(key2, value);
+    },
+    get: (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const value = adapter.get(key2);
+      if (isValid && !isValid(value)) {
+        console.warn(
+          `localStorage adapter: Auto-discard invalid value for ${key2}: ${JSON.stringify(value)}`
+        );
+        adapter.delete(key2);
+        return void 0;
+      }
+      return value;
+    },
+    delete: (key2) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.delete(key2);
+    },
+    clear: () => {
+      if (IS_NOT_BROWSER) return;
+      adapter.clear();
+    }
+  };
+}
+function kvStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const keyPrefix = key + ":";
+  return {
+    set: async (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.set(keyPrefix + key2, value, expiryMs);
+    },
+    get: async (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const fullKey = keyPrefix + key2;
+      const value = await kvStore.get(fullKey);
+      if (isValid && !isValid(value)) {
+        console.warn(
+          `indexedDb adapter: Auto-discard invalid value for ${key2}: ${JSON.stringify(value)}`
+        );
+        await kvStore.delete(fullKey);
+        return void 0;
+      }
+      return value;
+    },
+    delete: async (key2) => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.delete(keyPrefix + key2);
+    },
+    clear: async () => {
+      if (IS_NOT_BROWSER) return;
+      await kvStore.clear();
+    }
+  };
+}
 
 // src/sharedState.ts
 var SharedStateConfig = {
@@ -101,41 +110,11 @@ var SharedStateConfig = {
 function configureSharedState(config) {
   Object.assign(SharedStateConfig, config);
 }
-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);
+function createPubSubStore() {
+  const dataByKey = /* @__PURE__ */ new Map();
+  const subscribersByKey = /* @__PURE__ */ new Map();
+  function notify(key, next, prev) {
+    const subscribers = subscribersByKey.get(key);
     if (!subscribers) return;
     const copy = Array.from(subscribers.values());
     for (const subscriber of copy) {
@@ -146,115 +125,148 @@ var PubSubStore = class {
       }
     }
   }
-};
-var pubSubStore = new PubSubStore();
+  return {
+    // 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 dataByKey.get(key);
+    },
+    set(key, value) {
+      const prev = dataByKey.get(key);
+      if (prev === value) return;
+      dataByKey.set(key, value);
+      notify(key, value, prev);
+    },
+    delete(key) {
+      dataByKey.delete(key);
+    },
+    setNoNotify(key, value) {
+      dataByKey.set(key, value);
+    },
+    // Subscribe to changes of a specific key
+    subscribe(key, subscriber) {
+      let subscribers = subscribersByKey.get(key);
+      if (!subscribers) {
+        subscribers = /* @__PURE__ */ new Set();
+        subscribersByKey.set(key, subscribers);
+      }
+      subscribers.add(subscriber);
+      return () => {
+        subscribers.delete(subscriber);
+        if (subscribers.size === 0) subscribersByKey.delete(key);
+      };
+    }
+  };
+}
+var pubSubStore = createPubSubStore();
 var STORAGE_KEY = "state";
 var stateKey = 0;
-var SharedState = class {
-  constructor(defaultValue, options) {
-    this.defaultValue = defaultValue;
-    this.pubSubKey = String(stateKey++);
-    this.storageAdapter = getStorageAdapter(
-      options,
-      SharedStateConfig.storeExpiryMs
-    );
-    this.setValueBounded = (next) => {
-      this.setValue(next);
-    };
-    pubSubStore.setNoNotify(this.pubSubKey, defaultValue);
-    const lazyLoad = options?.lazyLoad;
-    const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
-    if (!lazy) {
-      void this.initDefaultValueOnce();
-    }
-  }
-  pubSubKey;
-  storageAdapter;
-  setValueBounded;
-  initStarted = false;
-  initDone = false;
-  /** `subscribe` function required by useSyncExternalStore. */
-  subscribe(subscriber) {
-    return pubSubStore.subscribe(this.pubSubKey, () => subscriber());
-  }
-  /** Returns true if there is a backing store. */
-  hasStore() {
-    return Boolean(this.storageAdapter);
-  }
-  /**
-   * Set a value directly into the store. Does nothing if there is no
-   * backing store.
-   *
-   * Warning: If you want to set the value properly, you should use
-   * `setValue()` instead which also updates the in-memory copy.
-   */
-  async setInStore(value) {
-    return await this.storageAdapter?.set(STORAGE_KEY, value);
-  }
-  /**
-   * Get a value directly from the store. Returns undefined if there is no
-   * backing store.
-   */
-  async getFromStore() {
-    return await this.storageAdapter?.get(STORAGE_KEY);
-  }
-  /**
-   * Get the value of the shared state.
-   *  `getSnapshot` function — must return same ref if value unchanged.
-   * Note that this would return the default value if data init from store is
-   * not completed yet.
-   */
-  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);
+function sharedState(defaultValue, options) {
+  let readyResolve = () => {
+  };
+  const readyPromise = new Promise((resolve) => {
+    readyResolve = resolve;
+  });
+  const resolveReadyPromise = readyResolve;
+  const pubSubKey = String(stateKey++);
+  const storageAdapter = getStorageAdapter(
+    options,
+    SharedStateConfig.storeExpiryMs
+  );
+  pubSubStore.setNoNotify(pubSubKey, defaultValue);
+  const lazyLoad = options?.lazyLoad;
+  const lazy = lazyLoad !== void 0 ? lazyLoad : SharedStateConfig.lazyLoad;
+  const obj = {
+    /** Allow users to await for the completion of data init. */
+    readyPromise,
+    lazy,
+    initStarted: false,
+    initDone: false,
+    /** `subscribe` function required by useSyncExternalStore. */
+    subscribe(subscriber) {
+      return pubSubStore.subscribe(pubSubKey, () => subscriber());
+    },
+    /** Returns true if there is a backing store. */
+    hasStore() {
+      return Boolean(storageAdapter);
+    },
+    /**
+     * Set a value directly into the store. Does nothing if there is no
+     * backing store.
+     *
+     * Warning: If you want to set the value properly, you should use
+     * `setValue()` instead which also updates the in-memory copy.
+     */
+    async setInStore(value) {
+      return await storageAdapter?.set(STORAGE_KEY, value);
+    },
+    /**
+     * Get a value directly from the store. Returns undefined if there is no
+     * backing store.
+     */
+    async getFromStore() {
+      return await storageAdapter?.get(STORAGE_KEY);
+    },
+    /**
+     * Get the value of the shared state.
+     *  `getSnapshot` function — must return same ref if value unchanged.
+     * Note that this would return the default value if data init from store is
+     * not completed yet.
+     */
+    getSnapshot() {
+      return pubSubStore.get(pubSubKey);
+    },
+    /** Set the value of the shared state. */
+    setValue(next) {
+      if (typeof next === "function") {
+        const prev = pubSubStore.get(pubSubKey);
+        next = next(prev);
+      }
+      pubSubStore.set(pubSubKey, next);
+      void obj.setInStore(next);
+    },
+    /**
+     * Remove the value of the shared state. Actually this just sets the value
+     * back to the given default value.
+     */
+    delete() {
+      pubSubStore.set(pubSubKey, defaultValue);
+      void storageAdapter?.set(STORAGE_KEY, defaultValue);
+    },
+    /** Initial default handling. */
+    async initDefaultValueOnce() {
+      if (obj.initDone || obj.initStarted) return;
+      obj.initStarted = true;
+      const stored = await obj.getFromStore();
+      const value = stored !== void 0 ? stored : defaultValue;
+      pubSubStore.set(pubSubKey, value);
+      obj.initDone = true;
+      resolveReadyPromise();
     }
-    pubSubStore.set(this.pubSubKey, next);
-    void this.setInStore(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?.set(STORAGE_KEY, this.defaultValue);
-  }
-  /** Initial default handling. */
-  async initDefaultValueOnce() {
-    if (this.initDone || this.initStarted) return;
-    this.initStarted = true;
-    const stored = await this.getFromStore();
-    const value = stored !== void 0 ? stored : this.defaultValue;
-    pubSubStore.set(this.pubSubKey, value);
-    this.initDone = true;
+  };
+  if (!lazy) {
+    void obj.initDefaultValueOnce();
   }
-};
-function sharedState(defaultValue, options) {
-  return new SharedState(defaultValue, options);
+  return obj;
 }
 function useSharedState(state) {
-  state.initDefaultValueOnce();
+  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];
+  return [value, state.setValue];
 }
 function useSharedStateValue(state) {
   return useSharedState(state)[0];
 }
 function useSharedStateSetter(state) {
-  return useSharedState(state)[1];
+  void state.initDefaultValueOnce();
+  return state.setValue;
 }
 export {
-  SharedState,
   SharedStateConfig,
   configureSharedState,
   sharedState,

package/storage.cjs

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/storage.ts
 var storage_exports = {};
 __export(storage_exports, {
-  getStorageAdapter: () => getStorageAdapter
+  getStorageAdapter: () => getStorageAdapter,
+  kvStoreAdapter: () => kvStoreAdapter,
+  localStoreAdapter: () => localStoreAdapter
 });
 module.exports = __toCommonJS(storage_exports);
 var import_kvStore = require("@choksheak/ts-utils/kvStore");
@@ -33,70 +35,12 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   if ("persistTo" in store && typeof store.persistTo === "string" && "key" in store && typeof store.key === "string") {
     const expiryMs = store.expiryMs || defaultStoreExpiryMs;
-    const isValid = store.isValid;
+    const config = { ...store, expiryMs };
     switch (store.persistTo) {
-      case "localStorage": {
-        const adapter = new import_localStore.LocalStore(store.key, {
-          defaultExpiryMs: expiryMs
-        });
-        return {
-          set: (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.set(key, value);
-          },
-          get: (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const value = adapter.get(key);
-            if (isValid && !isValid(value)) {
-              console.warn(
-                `localStorage adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              adapter.delete(key);
-              return void 0;
-            }
-            return value;
-          },
-          delete: (key) => {
-            if (IS_NOT_BROWSER) return;
-            adapter.delete(key);
-          },
-          clear: () => {
-            if (IS_NOT_BROWSER) return;
-            adapter.clear();
-          }
-        };
-      }
-      case "indexedDb": {
-        const keyPrefix = store.key + ":";
-        const isValid2 = store.isValid;
-        return {
-          set: async (key, value) => {
-            if (IS_NOT_BROWSER) return;
-            await import_kvStore.kvStore.set(keyPrefix + key, value, expiryMs);
-          },
-          get: async (key) => {
-            if (IS_NOT_BROWSER) return void 0;
-            const fullKey = keyPrefix + key;
-            const value = await import_kvStore.kvStore.get(fullKey);
-            if (isValid2 && !isValid2(value)) {
-              console.warn(
-                `indexedDb adapter: Auto-discard invalid value for ${key}: ${JSON.stringify(value)}`
-              );
-              await import_kvStore.kvStore.delete(fullKey);
-              return void 0;
-            }
-            return value;
-          },
-          delete: async (key) => {
-            if (IS_NOT_BROWSER) return;
-            await import_kvStore.kvStore.delete(keyPrefix + key);
-          },
-          clear: async () => {
-            if (IS_NOT_BROWSER) return;
-            await import_kvStore.kvStore.clear();
-          }
-        };
-      }
+      case "localStorage":
+        return localStoreAdapter(config);
+      case "indexedDb":
+        return kvStoreAdapter(config);
       default:
         store.persistTo;
         throw new Error(`Unknown store.adapter ${store.persistTo}`);
@@ -104,7 +48,76 @@ function getStorageAdapter(options, defaultStoreExpiryMs) {
   }
   return store;
 }
+function localStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const adapter = (0, import_localStore.createLocalStore)(key, { defaultExpiryMs: expiryMs });
+  return {
+    set: (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.set(key2, value);
+    },
+    get: (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const value = adapter.get(key2);
+      if (isValid && !isValid(value)) {
+        console.warn(
+          `localStorage adapter: Auto-discard invalid value for ${key2}: ${JSON.stringify(value)}`
+        );
+        adapter.delete(key2);
+        return void 0;
+      }
+      return value;
+    },
+    delete: (key2) => {
+      if (IS_NOT_BROWSER) return;
+      adapter.delete(key2);
+    },
+    clear: () => {
+      if (IS_NOT_BROWSER) return;
+      adapter.clear();
+    }
+  };
+}
+function kvStoreAdapter({
+  key,
+  expiryMs,
+  isValid
+}) {
+  const keyPrefix = key + ":";
+  return {
+    set: async (key2, value) => {
+      if (IS_NOT_BROWSER) return;
+      await import_kvStore.kvStore.set(keyPrefix + key2, value, expiryMs);
+    },
+    get: async (key2) => {
+      if (IS_NOT_BROWSER) return void 0;
+      const fullKey = keyPrefix + key2;
+      const value = await import_kvStore.kvStore.get(fullKey);
+      if (isValid && !isValid(value)) {
+        console.warn(
+          `indexedDb adapter: Auto-discard invalid value for ${key2}: ${JSON.stringify(value)}`
+        );
+        await import_kvStore.kvStore.delete(fullKey);
+        return void 0;
+      }
+      return value;
+    },
+    delete: async (key2) => {
+      if (IS_NOT_BROWSER) return;
+      await import_kvStore.kvStore.delete(keyPrefix + key2);
+    },
+    clear: async () => {
+      if (IS_NOT_BROWSER) return;
+      await import_kvStore.kvStore.clear();
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  getStorageAdapter
+  getStorageAdapter,
+  kvStoreAdapter,
+  localStoreAdapter
 });

package/storage.d.mts

@@ -1,5 +1,17 @@
+import { Duration } from '@choksheak/ts-utils/duration';
 import { StorageAdapter } from '@choksheak/ts-utils/storageAdapter';
 
+/**
+ * @packageDocumentation
+ *
+ * Backing storage implementation for the shared state. Note that this uses the
+ * LocalStore and KvStore from package "@choksheak/ts-utils", but is customized
+ * to be used for shared states.
+ *
+ * Normally you will not need to use this module directly, but if you have a
+ * need for it, feel free to use it.
+ */
+
 /** List of all available pre-built persistence options. */
 type PersistTo = "localStorage" | "indexedDb";
 /** Options to configure a pre-built store adapter. */
@@ -9,10 +21,11 @@ type StoreOptions = {
     /** Storage key to act as a namespace to store the data. */
     key: string;
     /** How long to wait before the value is considered expired. */
-    expiryMs?: number;
+    expiryMs?: number | Duration;
     /** Returns true if the given value supposed to be of type T is valid. */
     isValid?: (u: unknown) => boolean;
 };
+type StoreConstructorArgs = Omit<StoreOptions, "persistTo">;
 /** Either use a pre-built store, or a custom one you provide. */
 type StorageOptions<T> = {
     /**
@@ -21,6 +34,30 @@ type StorageOptions<T> = {
      */
     store?: StorageAdapter<T> | StoreOptions;
 };
+/**
+ * Convert a StorageOptions<T> config object into an actual storage adapter, or
+ * returns null if a storage adapter is not configured.
+ */
 declare function getStorageAdapter<T>(options: StorageOptions<T> | undefined, defaultStoreExpiryMs: number): StorageAdapter<T> | null;
+/**
+ * Create a new SSR-safe local store adapter, which allows users to reuse the
+ * same adapter in multiple shared states or shared queries.
+ */
+declare function localStoreAdapter<T>({ key, expiryMs, isValid, }: StoreConstructorArgs): {
+    set: (key: string, value: T) => void;
+    get: (key: string) => T | undefined;
+    delete: (key: string) => void;
+    clear: () => void;
+};
+/**
+ * Create a new SSR-safe indexed DB KV store adapter, which allows users to
+ * reuse the same adapter in multiple shared states or shared queries.
+ */
+declare function kvStoreAdapter<T>({ key, expiryMs, isValid, }: StoreConstructorArgs): {
+    set: (key: string, value: T) => Promise<void>;
+    get: (key: string) => Promise<T | undefined>;
+    delete: (key: string) => Promise<void>;
+    clear: () => Promise<void>;
+};
 
-export { type PersistTo, type StorageOptions, type StoreOptions, getStorageAdapter };
+export { type PersistTo, type StorageOptions, type StoreConstructorArgs, type StoreOptions, getStorageAdapter, kvStoreAdapter, localStoreAdapter };