@usefy/use-session-storage 0.0.20 → 0.0.22

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">@usefy/use-session-storage</h1>
 
 <p align="center">
-  <strong>A lightweight React hook for persisting state in sessionStorage</strong>
+  <strong>A lightweight React hook for persisting state in sessionStorage with automatic same-tab synchronization</strong>
 </p>
 
 <p align="center">
@@ -35,7 +35,7 @@
 
 ## Overview
 
-`@usefy/use-session-storage` provides a `useState`-like API for persisting data in sessionStorage. Data persists during the browser session (tab lifetime) but clears when the tab is closed. Each tab has isolated storage, making it perfect for temporary form data, wizard steps, and session-specific state.
+`@usefy/use-session-storage` provides a `useState`-like API for persisting data in sessionStorage. Features include **same-tab component synchronization**, custom serialization, lazy initialization, and error handling. Data persists during the browser session (tab lifetime) but clears when the tab is closed. Each tab has isolated storage, making it perfect for temporary form data, wizard steps, and session-specific state.
 
 **Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** — a collection of production-ready React hooks designed for modern applications.
 
@@ -44,7 +44,9 @@
 - **Zero Dependencies** — Pure React implementation with no external dependencies
 - **TypeScript First** — Full type safety with generics and exported interfaces
 - **useState-like API** — Familiar tuple return: `[value, setValue, removeValue]`
+- **Same-Tab Sync** — Multiple components using the same key stay in sync automatically
 - **Tab Isolation** — Each browser tab has its own session storage
+- **React 18+ Optimized** — Built with `useSyncExternalStore` for Concurrent Mode compatibility
 - **Auto-Cleanup** — Data cleared automatically when tab closes
 - **Custom Serialization** — Support for Date, Map, Set, or any custom type
 - **Lazy Initialization** — Function initializer support for expensive defaults
@@ -165,6 +167,39 @@ A hook that persists state in sessionStorage for the duration of the browser ses
 
 ## Examples
 
+### Same-Tab Component Synchronization
+
+```tsx
+import { useSessionStorage } from "@usefy/use-session-storage";
+
+// Multiple components using the same key automatically stay in sync!
+function WizardProgress() {
+  const [step] = useSessionStorage("wizard-step", 1);
+  return <ProgressBar current={step} total={5} />;
+}
+
+function WizardNavigation() {
+  const [step, setStep] = useSessionStorage("wizard-step", 1);
+
+  return (
+    <div>
+      <button onClick={() => setStep((s) => s - 1)} disabled={step === 1}>
+        Back
+      </button>
+      <button onClick={() => setStep((s) => s + 1)} disabled={step === 5}>
+        Next {/* WizardProgress automatically updates! */}
+      </button>
+    </div>
+  );
+}
+
+function WizardContent() {
+  const [step] = useSessionStorage("wizard-step", 1);
+  // Also updates when WizardNavigation changes step!
+  return <StepContent step={step} />;
+}
+```
+
 ### Multi-Step Wizard
 
 ```tsx
@@ -487,12 +522,7 @@ This package maintains comprehensive test coverage to ensure reliability and sta
 
 ### Test Coverage
 
-| Category   | Coverage       |
-| ---------- | -------------- |
-| Statements | 93.75% (45/48) |
-| Branches   | 78.94% (15/19) |
-| Functions  | 100% (6/6)     |
-| Lines      | 93.75% (45/48) |
+📊 <a href="https://geon0529.github.io/usefy/coverage/use-session-storage/src/index.html" target="_blank" rel="noopener noreferrer"><strong>View Detailed Coverage Report</strong></a> (GitHub Pages)
 
 ### Test Categories
 
@@ -508,6 +538,19 @@ This package maintains comprehensive test coverage to ensure reliability and sta
 
 </details>
 
+<details>
+<summary><strong>Same-Tab Sync Tests</strong></summary>
+
+- Sync ComponentB when ComponentA updates the same key
+- Sync multiple components using the same key
+- Sync when using functional updates
+- Sync when removeValue is called
+- Not affect components with different keys
+- Handle rapid updates from different components
+- Cleanup listeners on unmount
+
+</details>
+
 <details>
 <summary><strong>setValue Tests</strong></summary>
 

package/dist/index.d.mts

@@ -33,9 +33,13 @@ type UseSessionStorageReturn<T> = readonly [
     () => void
 ];
 /**
- * A hook for persisting state in sessionStorage.
+ * A hook for persisting state in sessionStorage with automatic synchronization.
  * Works like useState but persists the value in sessionStorage for the duration of the browser session.
  *
+ * Features:
+ * - Same-tab synchronization: Multiple components using the same key will stay in sync
+ * - SSR compatible: Works with Next.js, Remix, and other SSR frameworks
+ *
  * Unlike localStorage, sessionStorage data:
  * - Is cleared when the tab/window is closed
  * - Is not shared between tabs (each tab has its own session)
@@ -69,6 +73,21 @@ type UseSessionStorageReturn<T> = readonly [
  *
  * @example
  * ```tsx
+ * // Same-tab synchronization - both components stay in sync
+ * function ComponentA() {
+ *   const [step, setStep] = useSessionStorage('wizard-step', 1);
+ *   return <button onClick={() => setStep(s => s + 1)}>Next Step</button>;
+ * }
+ *
+ * function ComponentB() {
+ *   const [step] = useSessionStorage('wizard-step', 1);
+ *   // Automatically updates when ComponentA calls setStep!
+ *   return <p>Current Step: {step}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
  * // Temporary state that resets on tab close
  * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);
  * ```

package/dist/index.d.ts

@@ -33,9 +33,13 @@ type UseSessionStorageReturn<T> = readonly [
     () => void
 ];
 /**
- * A hook for persisting state in sessionStorage.
+ * A hook for persisting state in sessionStorage with automatic synchronization.
  * Works like useState but persists the value in sessionStorage for the duration of the browser session.
  *
+ * Features:
+ * - Same-tab synchronization: Multiple components using the same key will stay in sync
+ * - SSR compatible: Works with Next.js, Remix, and other SSR frameworks
+ *
  * Unlike localStorage, sessionStorage data:
  * - Is cleared when the tab/window is closed
  * - Is not shared between tabs (each tab has its own session)
@@ -69,6 +73,21 @@ type UseSessionStorageReturn<T> = readonly [
  *
  * @example
  * ```tsx
+ * // Same-tab synchronization - both components stay in sync
+ * function ComponentA() {
+ *   const [step, setStep] = useSessionStorage('wizard-step', 1);
+ *   return <button onClick={() => setStep(s => s + 1)}>Next Step</button>;
+ * }
+ *
+ * function ComponentB() {
+ *   const [step] = useSessionStorage('wizard-step', 1);
+ *   // Automatically updates when ComponentA calls setStep!
+ *   return <p>Current Step: {step}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
  * // Temporary state that resets on tab close
  * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);
  * ```

package/dist/index.js

@@ -26,6 +26,30 @@ module.exports = __toCommonJS(index_exports);
 
 // src/useSessionStorage.ts
 var import_react = require("react");
+
+// src/store.ts
+var listeners = /* @__PURE__ */ new Map();
+function subscribe(key, listener) {
+  if (!listeners.has(key)) {
+    listeners.set(key, /* @__PURE__ */ new Set());
+  }
+  const keyListeners = listeners.get(key);
+  keyListeners.add(listener);
+  return () => {
+    keyListeners.delete(listener);
+    if (keyListeners.size === 0) {
+      listeners.delete(key);
+    }
+  };
+}
+function notifyListeners(key) {
+  const keyListeners = listeners.get(key);
+  if (keyListeners) {
+    keyListeners.forEach((listener) => listener());
+  }
+}
+
+// src/useSessionStorage.ts
 function resolveInitialValue(initialValue) {
   return typeof initialValue === "function" ? initialValue() : initialValue;
 }
@@ -38,40 +62,79 @@ function useSessionStorage(key, initialValue, options = {}) {
   const serializerRef = (0, import_react.useRef)(serializer);
   const deserializerRef = (0, import_react.useRef)(deserializer);
   const onErrorRef = (0, import_react.useRef)(onError);
+  const initialValueRef = (0, import_react.useRef)(initialValue);
   serializerRef.current = serializer;
   deserializerRef.current = deserializer;
   onErrorRef.current = onError;
-  const initialValueRef = (0, import_react.useRef)(initialValue);
   initialValueRef.current = initialValue;
+  const cacheRef = (0, import_react.useRef)(
+    null
+  );
   const isClient = typeof window !== "undefined";
-  const [storedValue, setStoredValue] = (0, import_react.useState)(() => {
+  const subscribeToStore = (0, import_react.useCallback)(
+    (onStoreChange) => {
+      const unsubscribeStore = subscribe(key, onStoreChange);
+      return () => {
+        unsubscribeStore();
+      };
+    },
+    [key]
+  );
+  const getSnapshot = (0, import_react.useCallback)(() => {
     if (!isClient) {
-      return resolveInitialValue(initialValue);
+      return resolveInitialValue(initialValueRef.current);
     }
     try {
-      const item = window.sessionStorage.getItem(key);
-      if (item !== null) {
-        return deserializerRef.current(item);
+      const rawValue = window.sessionStorage.getItem(key);
+      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {
+        return cacheRef.current.parsedValue;
+      }
+      let parsedValue;
+      if (rawValue !== null) {
+        parsedValue = deserializerRef.current(rawValue);
+      } else {
+        parsedValue = resolveInitialValue(initialValueRef.current);
       }
-      return resolveInitialValue(initialValue);
+      cacheRef.current = { rawValue, parsedValue };
+      return parsedValue;
     } catch (error) {
       onErrorRef.current?.(error);
-      return resolveInitialValue(initialValue);
+      const fallbackValue = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: null, parsedValue: fallbackValue };
+      return fallbackValue;
     }
-  });
-  const storedValueRef = (0, import_react.useRef)(storedValue);
-  storedValueRef.current = storedValue;
+  }, [key, isClient]);
+  const getServerSnapshot = (0, import_react.useCallback)(() => {
+    return resolveInitialValue(initialValueRef.current);
+  }, []);
+  const storedValue = (0, import_react.useSyncExternalStore)(
+    subscribeToStore,
+    getSnapshot,
+    getServerSnapshot
+  );
   const setValue = (0, import_react.useCallback)(
     (value) => {
       try {
-        const currentValue = storedValueRef.current;
+        const currentValue = (() => {
+          try {
+            const item = window.sessionStorage.getItem(key);
+            if (item !== null) {
+              return deserializerRef.current(item);
+            }
+            return resolveInitialValue(initialValueRef.current);
+          } catch {
+            return resolveInitialValue(initialValueRef.current);
+          }
+        })();
         const valueToStore = value instanceof Function ? value(currentValue) : value;
-        setStoredValue(valueToStore);
         if (typeof window !== "undefined") {
-          window.sessionStorage.setItem(
-            key,
-            serializerRef.current(valueToStore)
-          );
+          const serialized = serializerRef.current(valueToStore);
+          window.sessionStorage.setItem(key, serialized);
+          cacheRef.current = {
+            rawValue: serialized,
+            parsedValue: valueToStore
+          };
+          notifyListeners(key);
         }
       } catch (error) {
         onErrorRef.current?.(error);
@@ -81,30 +144,16 @@ function useSessionStorage(key, initialValue, options = {}) {
   );
   const removeValue = (0, import_react.useCallback)(() => {
     try {
-      const initial = resolveInitialValue(initialValueRef.current);
-      setStoredValue(initial);
       if (typeof window !== "undefined") {
         window.sessionStorage.removeItem(key);
+        const initialVal = resolveInitialValue(initialValueRef.current);
+        cacheRef.current = { rawValue: null, parsedValue: initialVal };
+        notifyListeners(key);
       }
     } catch (error) {
       onErrorRef.current?.(error);
     }
   }, [key]);
-  (0, import_react.useEffect)(() => {
-    if (!isClient) {
-      return;
-    }
-    try {
-      const item = window.sessionStorage.getItem(key);
-      if (item !== null) {
-        setStoredValue(deserializerRef.current(item));
-      } else {
-        setStoredValue(resolveInitialValue(initialValueRef.current));
-      }
-    } catch {
-      setStoredValue(resolveInitialValue(initialValueRef.current));
-    }
-  }, [key]);
   return [storedValue, setValue, removeValue];
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/useSessionStorage.ts"],"sourcesContent":["export {\n  useSessionStorage,\n  type UseSessionStorageOptions,\n  type UseSessionStorageReturn,\n  type InitialValue,\n} from \"./useSessionStorage\";\n","import { useCallback, useEffect, useRef, useState } from \"react\";\n\n/**\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for useSessionStorage hook\n */\nexport interface UseSessionStorageOptions<T> {\n  /**\n   * Custom serializer function for converting value to string\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer function for parsing stored string to value\n   * @default JSON.parse\n   */\n  deserializer?: (value: string) => T;\n  /**\n   * Callback function called when an error occurs\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for useSessionStorage hook - tuple similar to useState\n */\nexport type UseSessionStorageReturn<T> = readonly [\n  /** Current stored value */\n  T,\n  /** Function to update the value (same signature as useState setter) */\n  React.Dispatch<React.SetStateAction<T>>,\n  /** Function to remove the value from sessionStorage */\n  () => void\n];\n\n/**\n * Helper function to resolve initial value (supports lazy initialization)\n */\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for persisting state in sessionStorage.\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\n *\n * Unlike localStorage, sessionStorage data:\n * - Is cleared when the tab/window is closed\n * - Is not shared between tabs (each tab has its own session)\n *\n * @template T - The type of the stored value\n * @param key - The sessionStorage key to store the value under\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\n * @param options - Configuration options for serialization and error handling\n * @returns A tuple of [storedValue, setValue, removeValue]\n *\n * @example\n * ```tsx\n * // Basic usage - form data that persists during session\n * function CheckoutForm() {\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\n *     name: '',\n *     email: '',\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={formData.name}\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\n *       />\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Temporary state that resets on tab close\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\n * ```\n *\n * @example\n * ```tsx\n * // With lazy initialization\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\n * ```\n *\n * @example\n * ```tsx\n * // With custom serializer/deserializer\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\n *   serializer: (d) => d.toISOString(),\n *   deserializer: (s) => new Date(s),\n * });\n * ```\n */\nexport function useSessionStorage<T>(\n  key: string,\n  initialValue: InitialValue<T>,\n  options: UseSessionStorageOptions<T> = {}\n): UseSessionStorageReturn<T> {\n  const {\n    serializer = JSON.stringify,\n    deserializer = JSON.parse,\n    onError,\n  } = options;\n\n  // Store options in refs for stable references and access to latest values\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n\n  // Store initialValue in ref for use in removeValue\n  const initialValueRef = useRef(initialValue);\n  initialValueRef.current = initialValue;\n\n  // SSR check\n  const isClient = typeof window !== \"undefined\";\n\n  // Lazy initialization with sessionStorage read\n  const [storedValue, setStoredValue] = useState<T>(() => {\n    if (!isClient) {\n      return resolveInitialValue(initialValue);\n    }\n\n    try {\n      const item = window.sessionStorage.getItem(key);\n      if (item !== null) {\n        return deserializerRef.current(item);\n      }\n      return resolveInitialValue(initialValue);\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      return resolveInitialValue(initialValue);\n    }\n  });\n\n  // Store current value in ref for stable setValue reference\n  const storedValueRef = useRef<T>(storedValue);\n  storedValueRef.current = storedValue;\n\n  // setValue - stable reference (only depends on key)\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\n    (value) => {\n      try {\n        const currentValue = storedValueRef.current;\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        setStoredValue(valueToStore);\n\n        if (typeof window !== \"undefined\") {\n          window.sessionStorage.setItem(\n            key,\n            serializerRef.current(valueToStore)\n          );\n        }\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // removeValue - stable reference\n  const removeValue = useCallback(() => {\n    try {\n      const initial = resolveInitialValue(initialValueRef.current);\n      setStoredValue(initial);\n\n      if (typeof window !== \"undefined\") {\n        window.sessionStorage.removeItem(key);\n      }\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  // Re-read value when key changes\n  useEffect(() => {\n    if (!isClient) {\n      return;\n    }\n\n    try {\n      const item = window.sessionStorage.getItem(key);\n      if (item !== null) {\n        setStoredValue(deserializerRef.current(item));\n      } else {\n        setStoredValue(resolveInitialValue(initialValueRef.current));\n      }\n    } catch {\n      setStoredValue(resolveInitialValue(initialValueRef.current));\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAAyD;AA0CzD,SAAS,oBAAuB,cAAkC;AAChE,SAAO,OAAO,iBAAiB,aAC1B,aAAyB,IAC1B;AACN;AA0DO,SAAS,kBACd,KACA,cACA,UAAuC,CAAC,GACZ;AAC5B,QAAM;AAAA,IACJ,aAAa,KAAK;AAAA,IAClB,eAAe,KAAK;AAAA,IACpB;AAAA,EACF,IAAI;AAGJ,QAAM,oBAAgB,qBAAO,UAAU;AACvC,QAAM,sBAAkB,qBAAO,YAAY;AAC3C,QAAM,iBAAa,qBAAO,OAAO;AACjC,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAC1B,aAAW,UAAU;AAGrB,QAAM,sBAAkB,qBAAO,YAAY;AAC3C,kBAAgB,UAAU;AAG1B,QAAM,WAAW,OAAO,WAAW;AAGnC,QAAM,CAAC,aAAa,cAAc,QAAI,uBAAY,MAAM;AACtD,QAAI,CAAC,UAAU;AACb,aAAO,oBAAoB,YAAY;AAAA,IACzC;AAEA,QAAI;AACF,YAAM,OAAO,OAAO,eAAe,QAAQ,GAAG;AAC9C,UAAI,SAAS,MAAM;AACjB,eAAO,gBAAgB,QAAQ,IAAI;AAAA,MACrC;AACA,aAAO,oBAAoB,YAAY;AAAA,IACzC,SAAS,OAAO;AACd,iBAAW,UAAU,KAAc;AACnC,aAAO,oBAAoB,YAAY;AAAA,IACzC;AAAA,EACF,CAAC;AAGD,QAAM,qBAAiB,qBAAU,WAAW;AAC5C,iBAAe,UAAU;AAGzB,QAAM,eAAW;AAAA,IACf,CAAC,UAAU;AACT,UAAI;AACF,cAAM,eAAe,eAAe;AACpC,cAAM,eACJ,iBAAiB,WAAW,MAAM,YAAY,IAAI;AAEpD,uBAAe,YAAY;AAE3B,YAAI,OAAO,WAAW,aAAa;AACjC,iBAAO,eAAe;AAAA,YACpB;AAAA,YACA,cAAc,QAAQ,YAAY;AAAA,UACpC;AAAA,QACF;AAAA,MACF,SAAS,OAAO;AACd,mBAAW,UAAU,KAAc;AAAA,MACrC;AAAA,IACF;AAAA,IACA,CAAC,GAAG;AAAA,EACN;AAGA,QAAM,kBAAc,0BAAY,MAAM;AACpC,QAAI;AACF,YAAM,UAAU,oBAAoB,gBAAgB,OAAO;AAC3D,qBAAe,OAAO;AAEtB,UAAI,OAAO,WAAW,aAAa;AACjC,eAAO,eAAe,WAAW,GAAG;AAAA,MACtC;AAAA,IACF,SAAS,OAAO;AACd,iBAAW,UAAU,KAAc;AAAA,IACrC;AAAA,EACF,GAAG,CAAC,GAAG,CAAC;AAGR,8BAAU,MAAM;AACd,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AAEA,QAAI;AACF,YAAM,OAAO,OAAO,eAAe,QAAQ,GAAG;AAC9C,UAAI,SAAS,MAAM;AACjB,uBAAe,gBAAgB,QAAQ,IAAI,CAAC;AAAA,MAC9C,OAAO;AACL,uBAAe,oBAAoB,gBAAgB,OAAO,CAAC;AAAA,MAC7D;AAAA,IACF,QAAQ;AACN,qBAAe,oBAAoB,gBAAgB,OAAO,CAAC;AAAA,IAC7D;AAAA,EAEF,GAAG,CAAC,GAAG,CAAC;AAER,SAAO,CAAC,aAAa,UAAU,WAAW;AAC5C;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/useSessionStorage.ts","../src/store.ts"],"sourcesContent":["export {\n  useSessionStorage,\n  type UseSessionStorageOptions,\n  type UseSessionStorageReturn,\n  type InitialValue,\n} from \"./useSessionStorage\";\n","import { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { subscribe, notifyListeners } from \"./store\";\n\n/**\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for useSessionStorage hook\n */\nexport interface UseSessionStorageOptions<T> {\n  /**\n   * Custom serializer function for converting value to string\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer function for parsing stored string to value\n   * @default JSON.parse\n   */\n  deserializer?: (value: string) => T;\n  /**\n   * Callback function called when an error occurs\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for useSessionStorage hook - tuple similar to useState\n */\nexport type UseSessionStorageReturn<T> = readonly [\n  /** Current stored value */\n  T,\n  /** Function to update the value (same signature as useState setter) */\n  React.Dispatch<React.SetStateAction<T>>,\n  /** Function to remove the value from sessionStorage */\n  () => void\n];\n\n/**\n * Helper function to resolve initial value (supports lazy initialization)\n */\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for persisting state in sessionStorage with automatic synchronization.\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\n *\n * Features:\n * - Same-tab synchronization: Multiple components using the same key will stay in sync\n * - SSR compatible: Works with Next.js, Remix, and other SSR frameworks\n *\n * Unlike localStorage, sessionStorage data:\n * - Is cleared when the tab/window is closed\n * - Is not shared between tabs (each tab has its own session)\n *\n * @template T - The type of the stored value\n * @param key - The sessionStorage key to store the value under\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\n * @param options - Configuration options for serialization and error handling\n * @returns A tuple of [storedValue, setValue, removeValue]\n *\n * @example\n * ```tsx\n * // Basic usage - form data that persists during session\n * function CheckoutForm() {\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\n *     name: '',\n *     email: '',\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={formData.name}\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\n *       />\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Same-tab synchronization - both components stay in sync\n * function ComponentA() {\n *   const [step, setStep] = useSessionStorage('wizard-step', 1);\n *   return <button onClick={() => setStep(s => s + 1)}>Next Step</button>;\n * }\n *\n * function ComponentB() {\n *   const [step] = useSessionStorage('wizard-step', 1);\n *   // Automatically updates when ComponentA calls setStep!\n *   return <p>Current Step: {step}</p>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Temporary state that resets on tab close\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\n * ```\n *\n * @example\n * ```tsx\n * // With lazy initialization\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\n * ```\n *\n * @example\n * ```tsx\n * // With custom serializer/deserializer\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\n *   serializer: (d) => d.toISOString(),\n *   deserializer: (s) => new Date(s),\n * });\n * ```\n */\nexport function useSessionStorage<T>(\n  key: string,\n  initialValue: InitialValue<T>,\n  options: UseSessionStorageOptions<T> = {}\n): UseSessionStorageReturn<T> {\n  const {\n    serializer = JSON.stringify,\n    deserializer = JSON.parse,\n    onError,\n  } = options;\n\n  // Store options in refs for stable references and access to latest values\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  const initialValueRef = useRef(initialValue);\n\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n  initialValueRef.current = initialValue;\n\n  // Cache for getSnapshot to ensure stable returns and prevent infinite loops\n  // useSyncExternalStore requires getSnapshot to return the same reference\n  // if the data hasn't changed\n  const cacheRef = useRef<{ rawValue: string | null; parsedValue: T } | null>(\n    null\n  );\n\n  // SSR check\n  const isClient = typeof window !== \"undefined\";\n\n  // Subscribe function for useSyncExternalStore\n  // Handles same-tab synchronization (sessionStorage doesn't have cross-tab sync)\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      // Subscribe to same-tab changes via internal store\n      const unsubscribeStore = subscribe(key, onStoreChange);\n\n      // Note: sessionStorage doesn't fire storage events for changes in the same tab,\n      // and changes in other tabs don't affect this tab's sessionStorage.\n      // So we only use the internal store for synchronization.\n\n      return () => {\n        unsubscribeStore();\n      };\n    },\n    [key]\n  );\n\n  // getSnapshot: Read current value from sessionStorage with caching\n  const getSnapshot = useCallback((): T => {\n    if (!isClient) {\n      return resolveInitialValue(initialValueRef.current);\n    }\n\n    try {\n      const rawValue = window.sessionStorage.getItem(key);\n\n      // Check cache: if rawValue is the same, return cached parsed value\n      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {\n        return cacheRef.current.parsedValue;\n      }\n\n      // Parse new value\n      let parsedValue: T;\n      if (rawValue !== null) {\n        parsedValue = deserializerRef.current(rawValue);\n      } else {\n        parsedValue = resolveInitialValue(initialValueRef.current);\n      }\n\n      // Update cache\n      cacheRef.current = { rawValue, parsedValue };\n\n      return parsedValue;\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      const fallbackValue = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: null, parsedValue: fallbackValue };\n      return fallbackValue;\n    }\n  }, [key, isClient]);\n\n  // getServerSnapshot: Return initial value for SSR\n  const getServerSnapshot = useCallback((): T => {\n    return resolveInitialValue(initialValueRef.current);\n  }, []);\n\n  // Use useSyncExternalStore for synchronized state\n  const storedValue = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // setValue - stable reference that updates sessionStorage and notifies listeners\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\n    (value) => {\n      try {\n        // Get current value for functional updates\n        const currentValue = (() => {\n          try {\n            const item = window.sessionStorage.getItem(key);\n            if (item !== null) {\n              return deserializerRef.current(item);\n            }\n            return resolveInitialValue(initialValueRef.current);\n          } catch {\n            return resolveInitialValue(initialValueRef.current);\n          }\n        })();\n\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        if (typeof window !== \"undefined\") {\n          const serialized = serializerRef.current(valueToStore);\n          window.sessionStorage.setItem(key, serialized);\n\n          // Invalidate cache so next getSnapshot reads fresh value\n          cacheRef.current = {\n            rawValue: serialized,\n            parsedValue: valueToStore,\n          };\n\n          // Notify all same-tab listeners\n          notifyListeners(key);\n        }\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // removeValue - stable reference\n  const removeValue = useCallback(() => {\n    try {\n      if (typeof window !== \"undefined\") {\n        window.sessionStorage.removeItem(key);\n\n        // Invalidate cache\n        const initialVal = resolveInitialValue(initialValueRef.current);\n        cacheRef.current = { rawValue: null, parsedValue: initialVal };\n\n        // Notify all same-tab listeners\n        notifyListeners(key);\n      }\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n","/**\n * Internal Store Manager for sessionStorage synchronization\n * This module manages listeners for same-tab synchronization across components\n * using the same sessionStorage key.\n *\n * @internal This module is not exported publicly\n */\n\n/** Map of key -> Set of listener callbacks */\nconst listeners = new Map<string, Set<() => void>>();\n\n/**\n * Subscribe a listener to changes for a specific key\n * @param key - The sessionStorage key to subscribe to\n * @param listener - Callback to invoke when the key's value changes\n * @returns Unsubscribe function\n */\nexport function subscribe(key: string, listener: () => void): () => void {\n  if (!listeners.has(key)) {\n    listeners.set(key, new Set());\n  }\n\n  const keyListeners = listeners.get(key)!;\n  keyListeners.add(listener);\n\n  return () => {\n    keyListeners.delete(listener);\n\n    // Cleanup: remove the key entry if no more listeners\n    if (keyListeners.size === 0) {\n      listeners.delete(key);\n    }\n  };\n}\n\n/**\n * Notify all listeners subscribed to a specific key\n * This is called when setValue or removeValue is invoked\n * to synchronize all components using the same key in the same tab\n *\n * @param key - The sessionStorage key that was updated\n */\nexport function notifyListeners(key: string): void {\n  const keyListeners = listeners.get(key);\n  if (keyListeners) {\n    keyListeners.forEach((listener) => listener());\n  }\n}\n\n/**\n * Get the count of listeners for a key (for testing purposes)\n * @internal\n */\nexport function getListenerCount(key: string): number {\n  return listeners.get(key)?.size ?? 0;\n}\n\n/**\n * Clear all listeners (for testing purposes)\n * @internal\n */\nexport function clearAllListeners(): void {\n  listeners.clear();\n}\n\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -1,5 +1,29 @@
 // src/useSessionStorage.ts
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+// src/store.ts
+var listeners = /* @__PURE__ */ new Map();
+function subscribe(key, listener) {
+  if (!listeners.has(key)) {
+    listeners.set(key, /* @__PURE__ */ new Set());
+  }
+  const keyListeners = listeners.get(key);
+  keyListeners.add(listener);
+  return () => {
+    keyListeners.delete(listener);
+    if (keyListeners.size === 0) {
+      listeners.delete(key);
+    }
+  };
+}
+function notifyListeners(key) {
+  const keyListeners = listeners.get(key);
+  if (keyListeners) {
+    keyListeners.forEach((listener) => listener());
+  }
+}
+
+// src/useSessionStorage.ts
 function resolveInitialValue(initialValue) {
   return typeof initialValue === "function" ? initialValue() : initialValue;
 }
@@ -12,40 +36,79 @@ function useSessionStorage(key, initialValue, options = {}) {
   const serializerRef = useRef(serializer);
   const deserializerRef = useRef(deserializer);
   const onErrorRef = useRef(onError);
+  const initialValueRef = useRef(initialValue);
   serializerRef.current = serializer;
   deserializerRef.current = deserializer;
   onErrorRef.current = onError;
-  const initialValueRef = useRef(initialValue);
   initialValueRef.current = initialValue;
+  const cacheRef = useRef(
+    null
+  );
   const isClient = typeof window !== "undefined";
-  const [storedValue, setStoredValue] = useState(() => {
+  const subscribeToStore = useCallback(
+    (onStoreChange) => {
+      const unsubscribeStore = subscribe(key, onStoreChange);
+      return () => {
+        unsubscribeStore();
+      };
+    },
+    [key]
+  );
+  const getSnapshot = useCallback(() => {
     if (!isClient) {
-      return resolveInitialValue(initialValue);
+      return resolveInitialValue(initialValueRef.current);
     }
     try {
-      const item = window.sessionStorage.getItem(key);
-      if (item !== null) {
-        return deserializerRef.current(item);
+      const rawValue = window.sessionStorage.getItem(key);
+      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {
+        return cacheRef.current.parsedValue;
       }
-      return resolveInitialValue(initialValue);
+      let parsedValue;
+      if (rawValue !== null) {
+        parsedValue = deserializerRef.current(rawValue);
+      } else {
+        parsedValue = resolveInitialValue(initialValueRef.current);
+      }
+      cacheRef.current = { rawValue, parsedValue };
+      return parsedValue;
     } catch (error) {
       onErrorRef.current?.(error);
-      return resolveInitialValue(initialValue);
+      const fallbackValue = resolveInitialValue(initialValueRef.current);
+      cacheRef.current = { rawValue: null, parsedValue: fallbackValue };
+      return fallbackValue;
     }
-  });
-  const storedValueRef = useRef(storedValue);
-  storedValueRef.current = storedValue;
+  }, [key, isClient]);
+  const getServerSnapshot = useCallback(() => {
+    return resolveInitialValue(initialValueRef.current);
+  }, []);
+  const storedValue = useSyncExternalStore(
+    subscribeToStore,
+    getSnapshot,
+    getServerSnapshot
+  );
   const setValue = useCallback(
     (value) => {
       try {
-        const currentValue = storedValueRef.current;
+        const currentValue = (() => {
+          try {
+            const item = window.sessionStorage.getItem(key);
+            if (item !== null) {
+              return deserializerRef.current(item);
+            }
+            return resolveInitialValue(initialValueRef.current);
+          } catch {
+            return resolveInitialValue(initialValueRef.current);
+          }
+        })();
         const valueToStore = value instanceof Function ? value(currentValue) : value;
-        setStoredValue(valueToStore);
         if (typeof window !== "undefined") {
-          window.sessionStorage.setItem(
-            key,
-            serializerRef.current(valueToStore)
-          );
+          const serialized = serializerRef.current(valueToStore);
+          window.sessionStorage.setItem(key, serialized);
+          cacheRef.current = {
+            rawValue: serialized,
+            parsedValue: valueToStore
+          };
+          notifyListeners(key);
         }
       } catch (error) {
         onErrorRef.current?.(error);
@@ -55,30 +118,16 @@ function useSessionStorage(key, initialValue, options = {}) {
   );
   const removeValue = useCallback(() => {
     try {
-      const initial = resolveInitialValue(initialValueRef.current);
-      setStoredValue(initial);
       if (typeof window !== "undefined") {
         window.sessionStorage.removeItem(key);
+        const initialVal = resolveInitialValue(initialValueRef.current);
+        cacheRef.current = { rawValue: null, parsedValue: initialVal };
+        notifyListeners(key);
       }
     } catch (error) {
       onErrorRef.current?.(error);
     }
   }, [key]);
-  useEffect(() => {
-    if (!isClient) {
-      return;
-    }
-    try {
-      const item = window.sessionStorage.getItem(key);
-      if (item !== null) {
-        setStoredValue(deserializerRef.current(item));
-      } else {
-        setStoredValue(resolveInitialValue(initialValueRef.current));
-      }
-    } catch {
-      setStoredValue(resolveInitialValue(initialValueRef.current));
-    }
-  }, [key]);
   return [storedValue, setValue, removeValue];
 }
 export {

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/useSessionStorage.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\n\n/**\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for useSessionStorage hook\n */\nexport interface UseSessionStorageOptions<T> {\n  /**\n   * Custom serializer function for converting value to string\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer function for parsing stored string to value\n   * @default JSON.parse\n   */\n  deserializer?: (value: string) => T;\n  /**\n   * Callback function called when an error occurs\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for useSessionStorage hook - tuple similar to useState\n */\nexport type UseSessionStorageReturn<T> = readonly [\n  /** Current stored value */\n  T,\n  /** Function to update the value (same signature as useState setter) */\n  React.Dispatch<React.SetStateAction<T>>,\n  /** Function to remove the value from sessionStorage */\n  () => void\n];\n\n/**\n * Helper function to resolve initial value (supports lazy initialization)\n */\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for persisting state in sessionStorage.\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\n *\n * Unlike localStorage, sessionStorage data:\n * - Is cleared when the tab/window is closed\n * - Is not shared between tabs (each tab has its own session)\n *\n * @template T - The type of the stored value\n * @param key - The sessionStorage key to store the value under\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\n * @param options - Configuration options for serialization and error handling\n * @returns A tuple of [storedValue, setValue, removeValue]\n *\n * @example\n * ```tsx\n * // Basic usage - form data that persists during session\n * function CheckoutForm() {\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\n *     name: '',\n *     email: '',\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={formData.name}\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\n *       />\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Temporary state that resets on tab close\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\n * ```\n *\n * @example\n * ```tsx\n * // With lazy initialization\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\n * ```\n *\n * @example\n * ```tsx\n * // With custom serializer/deserializer\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\n *   serializer: (d) => d.toISOString(),\n *   deserializer: (s) => new Date(s),\n * });\n * ```\n */\nexport function useSessionStorage<T>(\n  key: string,\n  initialValue: InitialValue<T>,\n  options: UseSessionStorageOptions<T> = {}\n): UseSessionStorageReturn<T> {\n  const {\n    serializer = JSON.stringify,\n    deserializer = JSON.parse,\n    onError,\n  } = options;\n\n  // Store options in refs for stable references and access to latest values\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n\n  // Store initialValue in ref for use in removeValue\n  const initialValueRef = useRef(initialValue);\n  initialValueRef.current = initialValue;\n\n  // SSR check\n  const isClient = typeof window !== \"undefined\";\n\n  // Lazy initialization with sessionStorage read\n  const [storedValue, setStoredValue] = useState<T>(() => {\n    if (!isClient) {\n      return resolveInitialValue(initialValue);\n    }\n\n    try {\n      const item = window.sessionStorage.getItem(key);\n      if (item !== null) {\n        return deserializerRef.current(item);\n      }\n      return resolveInitialValue(initialValue);\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      return resolveInitialValue(initialValue);\n    }\n  });\n\n  // Store current value in ref for stable setValue reference\n  const storedValueRef = useRef<T>(storedValue);\n  storedValueRef.current = storedValue;\n\n  // setValue - stable reference (only depends on key)\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\n    (value) => {\n      try {\n        const currentValue = storedValueRef.current;\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        setStoredValue(valueToStore);\n\n        if (typeof window !== \"undefined\") {\n          window.sessionStorage.setItem(\n            key,\n            serializerRef.current(valueToStore)\n          );\n        }\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // removeValue - stable reference\n  const removeValue = useCallback(() => {\n    try {\n      const initial = resolveInitialValue(initialValueRef.current);\n      setStoredValue(initial);\n\n      if (typeof window !== \"undefined\") {\n        window.sessionStorage.removeItem(key);\n      }\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  // Re-read value when key changes\n  useEffect(() => {\n    if (!isClient) {\n      return;\n    }\n\n    try {\n      const item = window.sessionStorage.getItem(key);\n      if (item !== null) {\n        setStoredValue(deserializerRef.current(item));\n      } else {\n        setStoredValue(resolveInitialValue(initialValueRef.current));\n      }\n    } catch {\n      setStoredValue(resolveInitialValue(initialValueRef.current));\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n"],"mappings":";AAAA,SAAS,aAAa,WAAW,QAAQ,gBAAgB;AA0CzD,SAAS,oBAAuB,cAAkC;AAChE,SAAO,OAAO,iBAAiB,aAC1B,aAAyB,IAC1B;AACN;AA0DO,SAAS,kBACd,KACA,cACA,UAAuC,CAAC,GACZ;AAC5B,QAAM;AAAA,IACJ,aAAa,KAAK;AAAA,IAClB,eAAe,KAAK;AAAA,IACpB;AAAA,EACF,IAAI;AAGJ,QAAM,gBAAgB,OAAO,UAAU;AACvC,QAAM,kBAAkB,OAAO,YAAY;AAC3C,QAAM,aAAa,OAAO,OAAO;AACjC,gBAAc,UAAU;AACxB,kBAAgB,UAAU;AAC1B,aAAW,UAAU;AAGrB,QAAM,kBAAkB,OAAO,YAAY;AAC3C,kBAAgB,UAAU;AAG1B,QAAM,WAAW,OAAO,WAAW;AAGnC,QAAM,CAAC,aAAa,cAAc,IAAI,SAAY,MAAM;AACtD,QAAI,CAAC,UAAU;AACb,aAAO,oBAAoB,YAAY;AAAA,IACzC;AAEA,QAAI;AACF,YAAM,OAAO,OAAO,eAAe,QAAQ,GAAG;AAC9C,UAAI,SAAS,MAAM;AACjB,eAAO,gBAAgB,QAAQ,IAAI;AAAA,MACrC;AACA,aAAO,oBAAoB,YAAY;AAAA,IACzC,SAAS,OAAO;AACd,iBAAW,UAAU,KAAc;AACnC,aAAO,oBAAoB,YAAY;AAAA,IACzC;AAAA,EACF,CAAC;AAGD,QAAM,iBAAiB,OAAU,WAAW;AAC5C,iBAAe,UAAU;AAGzB,QAAM,WAAW;AAAA,IACf,CAAC,UAAU;AACT,UAAI;AACF,cAAM,eAAe,eAAe;AACpC,cAAM,eACJ,iBAAiB,WAAW,MAAM,YAAY,IAAI;AAEpD,uBAAe,YAAY;AAE3B,YAAI,OAAO,WAAW,aAAa;AACjC,iBAAO,eAAe;AAAA,YACpB;AAAA,YACA,cAAc,QAAQ,YAAY;AAAA,UACpC;AAAA,QACF;AAAA,MACF,SAAS,OAAO;AACd,mBAAW,UAAU,KAAc;AAAA,MACrC;AAAA,IACF;AAAA,IACA,CAAC,GAAG;AAAA,EACN;AAGA,QAAM,cAAc,YAAY,MAAM;AACpC,QAAI;AACF,YAAM,UAAU,oBAAoB,gBAAgB,OAAO;AAC3D,qBAAe,OAAO;AAEtB,UAAI,OAAO,WAAW,aAAa;AACjC,eAAO,eAAe,WAAW,GAAG;AAAA,MACtC;AAAA,IACF,SAAS,OAAO;AACd,iBAAW,UAAU,KAAc;AAAA,IACrC;AAAA,EACF,GAAG,CAAC,GAAG,CAAC;AAGR,YAAU,MAAM;AACd,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AAEA,QAAI;AACF,YAAM,OAAO,OAAO,eAAe,QAAQ,GAAG;AAC9C,UAAI,SAAS,MAAM;AACjB,uBAAe,gBAAgB,QAAQ,IAAI,CAAC;AAAA,MAC9C,OAAO;AACL,uBAAe,oBAAoB,gBAAgB,OAAO,CAAC;AAAA,MAC7D;AAAA,IACF,QAAQ;AACN,qBAAe,oBAAoB,gBAAgB,OAAO,CAAC;AAAA,IAC7D;AAAA,EAEF,GAAG,CAAC,GAAG,CAAC;AAER,SAAO,CAAC,aAAa,UAAU,WAAW;AAC5C;","names":[]}
+{"version":3,"sources":["../src/useSessionStorage.ts","../src/store.ts"],"sourcesContent":["import { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { subscribe, notifyListeners } from \"./store\";\n\n/**\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\n */\nexport type InitialValue<T> = T | (() => T);\n\n/**\n * Options for useSessionStorage hook\n */\nexport interface UseSessionStorageOptions<T> {\n  /**\n   * Custom serializer function for converting value to string\n   * @default JSON.stringify\n   */\n  serializer?: (value: T) => string;\n  /**\n   * Custom deserializer function for parsing stored string to value\n   * @default JSON.parse\n   */\n  deserializer?: (value: string) => T;\n  /**\n   * Callback function called when an error occurs\n   */\n  onError?: (error: Error) => void;\n}\n\n/**\n * Return type for useSessionStorage hook - tuple similar to useState\n */\nexport type UseSessionStorageReturn<T> = readonly [\n  /** Current stored value */\n  T,\n  /** Function to update the value (same signature as useState setter) */\n  React.Dispatch<React.SetStateAction<T>>,\n  /** Function to remove the value from sessionStorage */\n  () => void\n];\n\n/**\n * Helper function to resolve initial value (supports lazy initialization)\n */\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\n  return typeof initialValue === \"function\"\n    ? (initialValue as () => T)()\n    : initialValue;\n}\n\n/**\n * A hook for persisting state in sessionStorage with automatic synchronization.\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\n *\n * Features:\n * - Same-tab synchronization: Multiple components using the same key will stay in sync\n * - SSR compatible: Works with Next.js, Remix, and other SSR frameworks\n *\n * Unlike localStorage, sessionStorage data:\n * - Is cleared when the tab/window is closed\n * - Is not shared between tabs (each tab has its own session)\n *\n * @template T - The type of the stored value\n * @param key - The sessionStorage key to store the value under\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\n * @param options - Configuration options for serialization and error handling\n * @returns A tuple of [storedValue, setValue, removeValue]\n *\n * @example\n * ```tsx\n * // Basic usage - form data that persists during session\n * function CheckoutForm() {\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\n *     name: '',\n *     email: '',\n *   });\n *\n *   return (\n *     <form>\n *       <input\n *         value={formData.name}\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\n *       />\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\n *     </form>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Same-tab synchronization - both components stay in sync\n * function ComponentA() {\n *   const [step, setStep] = useSessionStorage('wizard-step', 1);\n *   return <button onClick={() => setStep(s => s + 1)}>Next Step</button>;\n * }\n *\n * function ComponentB() {\n *   const [step] = useSessionStorage('wizard-step', 1);\n *   // Automatically updates when ComponentA calls setStep!\n *   return <p>Current Step: {step}</p>;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Temporary state that resets on tab close\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\n * ```\n *\n * @example\n * ```tsx\n * // With lazy initialization\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\n * ```\n *\n * @example\n * ```tsx\n * // With custom serializer/deserializer\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\n *   serializer: (d) => d.toISOString(),\n *   deserializer: (s) => new Date(s),\n * });\n * ```\n */\nexport function useSessionStorage<T>(\n  key: string,\n  initialValue: InitialValue<T>,\n  options: UseSessionStorageOptions<T> = {}\n): UseSessionStorageReturn<T> {\n  const {\n    serializer = JSON.stringify,\n    deserializer = JSON.parse,\n    onError,\n  } = options;\n\n  // Store options in refs for stable references and access to latest values\n  const serializerRef = useRef(serializer);\n  const deserializerRef = useRef(deserializer);\n  const onErrorRef = useRef(onError);\n  const initialValueRef = useRef(initialValue);\n\n  serializerRef.current = serializer;\n  deserializerRef.current = deserializer;\n  onErrorRef.current = onError;\n  initialValueRef.current = initialValue;\n\n  // Cache for getSnapshot to ensure stable returns and prevent infinite loops\n  // useSyncExternalStore requires getSnapshot to return the same reference\n  // if the data hasn't changed\n  const cacheRef = useRef<{ rawValue: string | null; parsedValue: T } | null>(\n    null\n  );\n\n  // SSR check\n  const isClient = typeof window !== \"undefined\";\n\n  // Subscribe function for useSyncExternalStore\n  // Handles same-tab synchronization (sessionStorage doesn't have cross-tab sync)\n  const subscribeToStore = useCallback(\n    (onStoreChange: () => void) => {\n      // Subscribe to same-tab changes via internal store\n      const unsubscribeStore = subscribe(key, onStoreChange);\n\n      // Note: sessionStorage doesn't fire storage events for changes in the same tab,\n      // and changes in other tabs don't affect this tab's sessionStorage.\n      // So we only use the internal store for synchronization.\n\n      return () => {\n        unsubscribeStore();\n      };\n    },\n    [key]\n  );\n\n  // getSnapshot: Read current value from sessionStorage with caching\n  const getSnapshot = useCallback((): T => {\n    if (!isClient) {\n      return resolveInitialValue(initialValueRef.current);\n    }\n\n    try {\n      const rawValue = window.sessionStorage.getItem(key);\n\n      // Check cache: if rawValue is the same, return cached parsed value\n      if (cacheRef.current && cacheRef.current.rawValue === rawValue) {\n        return cacheRef.current.parsedValue;\n      }\n\n      // Parse new value\n      let parsedValue: T;\n      if (rawValue !== null) {\n        parsedValue = deserializerRef.current(rawValue);\n      } else {\n        parsedValue = resolveInitialValue(initialValueRef.current);\n      }\n\n      // Update cache\n      cacheRef.current = { rawValue, parsedValue };\n\n      return parsedValue;\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n      const fallbackValue = resolveInitialValue(initialValueRef.current);\n      cacheRef.current = { rawValue: null, parsedValue: fallbackValue };\n      return fallbackValue;\n    }\n  }, [key, isClient]);\n\n  // getServerSnapshot: Return initial value for SSR\n  const getServerSnapshot = useCallback((): T => {\n    return resolveInitialValue(initialValueRef.current);\n  }, []);\n\n  // Use useSyncExternalStore for synchronized state\n  const storedValue = useSyncExternalStore(\n    subscribeToStore,\n    getSnapshot,\n    getServerSnapshot\n  );\n\n  // setValue - stable reference that updates sessionStorage and notifies listeners\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\n    (value) => {\n      try {\n        // Get current value for functional updates\n        const currentValue = (() => {\n          try {\n            const item = window.sessionStorage.getItem(key);\n            if (item !== null) {\n              return deserializerRef.current(item);\n            }\n            return resolveInitialValue(initialValueRef.current);\n          } catch {\n            return resolveInitialValue(initialValueRef.current);\n          }\n        })();\n\n        const valueToStore =\n          value instanceof Function ? value(currentValue) : value;\n\n        if (typeof window !== \"undefined\") {\n          const serialized = serializerRef.current(valueToStore);\n          window.sessionStorage.setItem(key, serialized);\n\n          // Invalidate cache so next getSnapshot reads fresh value\n          cacheRef.current = {\n            rawValue: serialized,\n            parsedValue: valueToStore,\n          };\n\n          // Notify all same-tab listeners\n          notifyListeners(key);\n        }\n      } catch (error) {\n        onErrorRef.current?.(error as Error);\n      }\n    },\n    [key]\n  );\n\n  // removeValue - stable reference\n  const removeValue = useCallback(() => {\n    try {\n      if (typeof window !== \"undefined\") {\n        window.sessionStorage.removeItem(key);\n\n        // Invalidate cache\n        const initialVal = resolveInitialValue(initialValueRef.current);\n        cacheRef.current = { rawValue: null, parsedValue: initialVal };\n\n        // Notify all same-tab listeners\n        notifyListeners(key);\n      }\n    } catch (error) {\n      onErrorRef.current?.(error as Error);\n    }\n  }, [key]);\n\n  return [storedValue, setValue, removeValue] as const;\n}\n","/**\n * Internal Store Manager for sessionStorage synchronization\n * This module manages listeners for same-tab synchronization across components\n * using the same sessionStorage key.\n *\n * @internal This module is not exported publicly\n */\n\n/** Map of key -> Set of listener callbacks */\nconst listeners = new Map<string, Set<() => void>>();\n\n/**\n * Subscribe a listener to changes for a specific key\n * @param key - The sessionStorage key to subscribe to\n * @param listener - Callback to invoke when the key's value changes\n * @returns Unsubscribe function\n */\nexport function subscribe(key: string, listener: () => void): () => void {\n  if (!listeners.has(key)) {\n    listeners.set(key, new Set());\n  }\n\n  const keyListeners = listeners.get(key)!;\n  keyListeners.add(listener);\n\n  return () => {\n    keyListeners.delete(listener);\n\n    // Cleanup: remove the key entry if no more listeners\n    if (keyListeners.size === 0) {\n      listeners.delete(key);\n    }\n  };\n}\n\n/**\n * Notify all listeners subscribed to a specific key\n * This is called when setValue or removeValue is invoked\n * to synchronize all components using the same key in the same tab\n *\n * @param key - The sessionStorage key that was updated\n */\nexport function notifyListeners(key: string): void {\n  const keyListeners = listeners.get(key);\n  if (keyListeners) {\n    keyListeners.forEach((listener) => listener());\n  }\n}\n\n/**\n * Get the count of listeners for a key (for testing purposes)\n * @internal\n */\nexport function getListenerCount(key: string): number {\n  return listeners.get(key)?.size ?? 0;\n}\n\n/**\n * Clear all listeners (for testing purposes)\n * @internal\n */\nexport function clearAllListeners(): void {\n  listeners.clear();\n}\n\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefy/use-session-storage",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "A React hook for persisting state in sessionStorage",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",