@usefy/use-session-storage 0.0.2

package/dist/index.d.mts

@@ -0,0 +1,93 @@
+/**
+ * Type for initial value that can be a value or a function returning a value (lazy initialization)
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for useSessionStorage hook
+ */
+interface UseSessionStorageOptions<T> {
+    /**
+     * Custom serializer function for converting value to string
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer function for parsing stored string to value
+     * @default JSON.parse
+     */
+    deserializer?: (value: string) => T;
+    /**
+     * Callback function called when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useSessionStorage hook - tuple similar to useState
+ */
+type UseSessionStorageReturn<T> = readonly [
+    /** Current stored value */
+    T,
+    /** Function to update the value (same signature as useState setter) */
+    React.Dispatch<React.SetStateAction<T>>,
+    /** Function to remove the value from sessionStorage */
+    () => void
+];
+/**
+ * A hook for persisting state in sessionStorage.
+ * Works like useState but persists the value in sessionStorage for the duration of the browser session.
+ *
+ * Unlike localStorage, sessionStorage data:
+ * - Is cleared when the tab/window is closed
+ * - Is not shared between tabs (each tab has its own session)
+ *
+ * @template T - The type of the stored value
+ * @param key - The sessionStorage key to store the value under
+ * @param initialValue - Initial value or function returning initial value (lazy initialization)
+ * @param options - Configuration options for serialization and error handling
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - form data that persists during session
+ * function CheckoutForm() {
+ *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {
+ *     name: '',
+ *     email: '',
+ *   });
+ *
+ *   return (
+ *     <form>
+ *       <input
+ *         value={formData.name}
+ *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
+ *       />
+ *       <button type="button" onClick={clearForm}>Clear</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Temporary state that resets on tab close
+ * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy initialization
+ * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom serializer/deserializer
+ * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {
+ *   serializer: (d) => d.toISOString(),
+ *   deserializer: (s) => new Date(s),
+ * });
+ * ```
+ */
+declare function useSessionStorage<T>(key: string, initialValue: InitialValue<T>, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+
+export { type InitialValue, type UseSessionStorageOptions, type UseSessionStorageReturn, useSessionStorage };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Type for initial value that can be a value or a function returning a value (lazy initialization)
+ */
+type InitialValue<T> = T | (() => T);
+/**
+ * Options for useSessionStorage hook
+ */
+interface UseSessionStorageOptions<T> {
+    /**
+     * Custom serializer function for converting value to string
+     * @default JSON.stringify
+     */
+    serializer?: (value: T) => string;
+    /**
+     * Custom deserializer function for parsing stored string to value
+     * @default JSON.parse
+     */
+    deserializer?: (value: string) => T;
+    /**
+     * Callback function called when an error occurs
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useSessionStorage hook - tuple similar to useState
+ */
+type UseSessionStorageReturn<T> = readonly [
+    /** Current stored value */
+    T,
+    /** Function to update the value (same signature as useState setter) */
+    React.Dispatch<React.SetStateAction<T>>,
+    /** Function to remove the value from sessionStorage */
+    () => void
+];
+/**
+ * A hook for persisting state in sessionStorage.
+ * Works like useState but persists the value in sessionStorage for the duration of the browser session.
+ *
+ * Unlike localStorage, sessionStorage data:
+ * - Is cleared when the tab/window is closed
+ * - Is not shared between tabs (each tab has its own session)
+ *
+ * @template T - The type of the stored value
+ * @param key - The sessionStorage key to store the value under
+ * @param initialValue - Initial value or function returning initial value (lazy initialization)
+ * @param options - Configuration options for serialization and error handling
+ * @returns A tuple of [storedValue, setValue, removeValue]
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - form data that persists during session
+ * function CheckoutForm() {
+ *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {
+ *     name: '',
+ *     email: '',
+ *   });
+ *
+ *   return (
+ *     <form>
+ *       <input
+ *         value={formData.name}
+ *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}
+ *       />
+ *       <button type="button" onClick={clearForm}>Clear</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Temporary state that resets on tab close
+ * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With lazy initialization
+ * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom serializer/deserializer
+ * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {
+ *   serializer: (d) => d.toISOString(),
+ *   deserializer: (s) => new Date(s),
+ * });
+ * ```
+ */
+declare function useSessionStorage<T>(key: string, initialValue: InitialValue<T>, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+
+export { type InitialValue, type UseSessionStorageOptions, type UseSessionStorageReturn, useSessionStorage };

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  useSessionStorage: () => useSessionStorage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useSessionStorage.ts
+var import_react = require("react");
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useSessionStorage(key, initialValue, options = {}) {
+  const {
+    serializer = JSON.stringify,
+    deserializer = JSON.parse,
+    onError
+  } = options;
+  const serializerRef = (0, import_react.useRef)(serializer);
+  const deserializerRef = (0, import_react.useRef)(deserializer);
+  const onErrorRef = (0, import_react.useRef)(onError);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  const initialValueRef = (0, import_react.useRef)(initialValue);
+  initialValueRef.current = initialValue;
+  const isClient = typeof window !== "undefined";
+  const [storedValue, setStoredValue] = (0, import_react.useState)(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValue);
+    }
+    try {
+      const item = window.sessionStorage.getItem(key);
+      if (item !== null) {
+        return deserializerRef.current(item);
+      }
+      return resolveInitialValue(initialValue);
+    } catch (error) {
+      onErrorRef.current?.(error);
+      return resolveInitialValue(initialValue);
+    }
+  });
+  const storedValueRef = (0, import_react.useRef)(storedValue);
+  storedValueRef.current = storedValue;
+  const setValue = (0, import_react.useCallback)(
+    (value) => {
+      try {
+        const currentValue = storedValueRef.current;
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        setStoredValue(valueToStore);
+        if (typeof window !== "undefined") {
+          window.sessionStorage.setItem(
+            key,
+            serializerRef.current(valueToStore)
+          );
+        }
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = (0, import_react.useCallback)(() => {
+    try {
+      const initial = resolveInitialValue(initialValueRef.current);
+      setStoredValue(initial);
+      if (typeof window !== "undefined") {
+        window.sessionStorage.removeItem(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:
+0 && (module.exports = {
+  useSessionStorage
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useSessionStorage.ts"],"sourcesContent":["export {\r\n  useSessionStorage,\r\n  type UseSessionStorageOptions,\r\n  type UseSessionStorageReturn,\r\n  type InitialValue,\r\n} from \"./useSessionStorage\";\r\n","import { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\r\n */\r\nexport type InitialValue<T> = T | (() => T);\r\n\r\n/**\r\n * Options for useSessionStorage hook\r\n */\r\nexport interface UseSessionStorageOptions<T> {\r\n  /**\r\n   * Custom serializer function for converting value to string\r\n   * @default JSON.stringify\r\n   */\r\n  serializer?: (value: T) => string;\r\n  /**\r\n   * Custom deserializer function for parsing stored string to value\r\n   * @default JSON.parse\r\n   */\r\n  deserializer?: (value: string) => T;\r\n  /**\r\n   * Callback function called when an error occurs\r\n   */\r\n  onError?: (error: Error) => void;\r\n}\r\n\r\n/**\r\n * Return type for useSessionStorage hook - tuple similar to useState\r\n */\r\nexport type UseSessionStorageReturn<T> = readonly [\r\n  /** Current stored value */\r\n  T,\r\n  /** Function to update the value (same signature as useState setter) */\r\n  React.Dispatch<React.SetStateAction<T>>,\r\n  /** Function to remove the value from sessionStorage */\r\n  () => void\r\n];\r\n\r\n/**\r\n * Helper function to resolve initial value (supports lazy initialization)\r\n */\r\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\r\n  return typeof initialValue === \"function\"\r\n    ? (initialValue as () => T)()\r\n    : initialValue;\r\n}\r\n\r\n/**\r\n * A hook for persisting state in sessionStorage.\r\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\r\n *\r\n * Unlike localStorage, sessionStorage data:\r\n * - Is cleared when the tab/window is closed\r\n * - Is not shared between tabs (each tab has its own session)\r\n *\r\n * @template T - The type of the stored value\r\n * @param key - The sessionStorage key to store the value under\r\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\r\n * @param options - Configuration options for serialization and error handling\r\n * @returns A tuple of [storedValue, setValue, removeValue]\r\n *\r\n * @example\r\n * ```tsx\r\n * // Basic usage - form data that persists during session\r\n * function CheckoutForm() {\r\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\r\n *     name: '',\r\n *     email: '',\r\n *   });\r\n *\r\n *   return (\r\n *     <form>\r\n *       <input\r\n *         value={formData.name}\r\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\r\n *       />\r\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\r\n *     </form>\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // Temporary state that resets on tab close\r\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With lazy initialization\r\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With custom serializer/deserializer\r\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\r\n *   serializer: (d) => d.toISOString(),\r\n *   deserializer: (s) => new Date(s),\r\n * });\r\n * ```\r\n */\r\nexport function useSessionStorage<T>(\r\n  key: string,\r\n  initialValue: InitialValue<T>,\r\n  options: UseSessionStorageOptions<T> = {}\r\n): UseSessionStorageReturn<T> {\r\n  const {\r\n    serializer = JSON.stringify,\r\n    deserializer = JSON.parse,\r\n    onError,\r\n  } = options;\r\n\r\n  // Store options in refs for stable references and access to latest values\r\n  const serializerRef = useRef(serializer);\r\n  const deserializerRef = useRef(deserializer);\r\n  const onErrorRef = useRef(onError);\r\n  serializerRef.current = serializer;\r\n  deserializerRef.current = deserializer;\r\n  onErrorRef.current = onError;\r\n\r\n  // Store initialValue in ref for use in removeValue\r\n  const initialValueRef = useRef(initialValue);\r\n  initialValueRef.current = initialValue;\r\n\r\n  // SSR check\r\n  const isClient = typeof window !== \"undefined\";\r\n\r\n  // Lazy initialization with sessionStorage read\r\n  const [storedValue, setStoredValue] = useState<T>(() => {\r\n    if (!isClient) {\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n\r\n    try {\r\n      const item = window.sessionStorage.getItem(key);\r\n      if (item !== null) {\r\n        return deserializerRef.current(item);\r\n      }\r\n      return resolveInitialValue(initialValue);\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n  });\r\n\r\n  // Store current value in ref for stable setValue reference\r\n  const storedValueRef = useRef<T>(storedValue);\r\n  storedValueRef.current = storedValue;\r\n\r\n  // setValue - stable reference (only depends on key)\r\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\r\n    (value) => {\r\n      try {\r\n        const currentValue = storedValueRef.current;\r\n        const valueToStore =\r\n          value instanceof Function ? value(currentValue) : value;\r\n\r\n        setStoredValue(valueToStore);\r\n\r\n        if (typeof window !== \"undefined\") {\r\n          window.sessionStorage.setItem(\r\n            key,\r\n            serializerRef.current(valueToStore)\r\n          );\r\n        }\r\n      } catch (error) {\r\n        onErrorRef.current?.(error as Error);\r\n      }\r\n    },\r\n    [key]\r\n  );\r\n\r\n  // removeValue - stable reference\r\n  const removeValue = useCallback(() => {\r\n    try {\r\n      const initial = resolveInitialValue(initialValueRef.current);\r\n      setStoredValue(initial);\r\n\r\n      if (typeof window !== \"undefined\") {\r\n        window.sessionStorage.removeItem(key);\r\n      }\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n    }\r\n  }, [key]);\r\n\r\n  // Re-read value when key changes\r\n  useEffect(() => {\r\n    if (!isClient) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const item = window.sessionStorage.getItem(key);\r\n      if (item !== null) {\r\n        setStoredValue(deserializerRef.current(item));\r\n      } else {\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    } catch {\r\n      setStoredValue(resolveInitialValue(initialValueRef.current));\r\n    }\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [key]);\r\n\r\n  return [storedValue, setValue, removeValue] as const;\r\n}\r\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":[]}

package/dist/index.mjs

@@ -0,0 +1,87 @@
+// src/useSessionStorage.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+function resolveInitialValue(initialValue) {
+  return typeof initialValue === "function" ? initialValue() : initialValue;
+}
+function useSessionStorage(key, initialValue, options = {}) {
+  const {
+    serializer = JSON.stringify,
+    deserializer = JSON.parse,
+    onError
+  } = options;
+  const serializerRef = useRef(serializer);
+  const deserializerRef = useRef(deserializer);
+  const onErrorRef = useRef(onError);
+  serializerRef.current = serializer;
+  deserializerRef.current = deserializer;
+  onErrorRef.current = onError;
+  const initialValueRef = useRef(initialValue);
+  initialValueRef.current = initialValue;
+  const isClient = typeof window !== "undefined";
+  const [storedValue, setStoredValue] = useState(() => {
+    if (!isClient) {
+      return resolveInitialValue(initialValue);
+    }
+    try {
+      const item = window.sessionStorage.getItem(key);
+      if (item !== null) {
+        return deserializerRef.current(item);
+      }
+      return resolveInitialValue(initialValue);
+    } catch (error) {
+      onErrorRef.current?.(error);
+      return resolveInitialValue(initialValue);
+    }
+  });
+  const storedValueRef = useRef(storedValue);
+  storedValueRef.current = storedValue;
+  const setValue = useCallback(
+    (value) => {
+      try {
+        const currentValue = storedValueRef.current;
+        const valueToStore = value instanceof Function ? value(currentValue) : value;
+        setStoredValue(valueToStore);
+        if (typeof window !== "undefined") {
+          window.sessionStorage.setItem(
+            key,
+            serializerRef.current(valueToStore)
+          );
+        }
+      } catch (error) {
+        onErrorRef.current?.(error);
+      }
+    },
+    [key]
+  );
+  const removeValue = useCallback(() => {
+    try {
+      const initial = resolveInitialValue(initialValueRef.current);
+      setStoredValue(initial);
+      if (typeof window !== "undefined") {
+        window.sessionStorage.removeItem(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 {
+  useSessionStorage
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useSessionStorage.ts"],"sourcesContent":["import { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\n/**\r\n * Type for initial value that can be a value or a function returning a value (lazy initialization)\r\n */\r\nexport type InitialValue<T> = T | (() => T);\r\n\r\n/**\r\n * Options for useSessionStorage hook\r\n */\r\nexport interface UseSessionStorageOptions<T> {\r\n  /**\r\n   * Custom serializer function for converting value to string\r\n   * @default JSON.stringify\r\n   */\r\n  serializer?: (value: T) => string;\r\n  /**\r\n   * Custom deserializer function for parsing stored string to value\r\n   * @default JSON.parse\r\n   */\r\n  deserializer?: (value: string) => T;\r\n  /**\r\n   * Callback function called when an error occurs\r\n   */\r\n  onError?: (error: Error) => void;\r\n}\r\n\r\n/**\r\n * Return type for useSessionStorage hook - tuple similar to useState\r\n */\r\nexport type UseSessionStorageReturn<T> = readonly [\r\n  /** Current stored value */\r\n  T,\r\n  /** Function to update the value (same signature as useState setter) */\r\n  React.Dispatch<React.SetStateAction<T>>,\r\n  /** Function to remove the value from sessionStorage */\r\n  () => void\r\n];\r\n\r\n/**\r\n * Helper function to resolve initial value (supports lazy initialization)\r\n */\r\nfunction resolveInitialValue<T>(initialValue: InitialValue<T>): T {\r\n  return typeof initialValue === \"function\"\r\n    ? (initialValue as () => T)()\r\n    : initialValue;\r\n}\r\n\r\n/**\r\n * A hook for persisting state in sessionStorage.\r\n * Works like useState but persists the value in sessionStorage for the duration of the browser session.\r\n *\r\n * Unlike localStorage, sessionStorage data:\r\n * - Is cleared when the tab/window is closed\r\n * - Is not shared between tabs (each tab has its own session)\r\n *\r\n * @template T - The type of the stored value\r\n * @param key - The sessionStorage key to store the value under\r\n * @param initialValue - Initial value or function returning initial value (lazy initialization)\r\n * @param options - Configuration options for serialization and error handling\r\n * @returns A tuple of [storedValue, setValue, removeValue]\r\n *\r\n * @example\r\n * ```tsx\r\n * // Basic usage - form data that persists during session\r\n * function CheckoutForm() {\r\n *   const [formData, setFormData, clearForm] = useSessionStorage('checkout-form', {\r\n *     name: '',\r\n *     email: '',\r\n *   });\r\n *\r\n *   return (\r\n *     <form>\r\n *       <input\r\n *         value={formData.name}\r\n *         onChange={(e) => setFormData(prev => ({ ...prev, name: e.target.value }))}\r\n *       />\r\n *       <button type=\"button\" onClick={clearForm}>Clear</button>\r\n *     </form>\r\n *   );\r\n * }\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // Temporary state that resets on tab close\r\n * const [wizardStep, setWizardStep] = useSessionStorage('wizard-step', 1);\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With lazy initialization\r\n * const [cache, setCache] = useSessionStorage('cache', () => computeInitialCache());\r\n * ```\r\n *\r\n * @example\r\n * ```tsx\r\n * // With custom serializer/deserializer\r\n * const [date, setDate] = useSessionStorage<Date>('lastAction', new Date(), {\r\n *   serializer: (d) => d.toISOString(),\r\n *   deserializer: (s) => new Date(s),\r\n * });\r\n * ```\r\n */\r\nexport function useSessionStorage<T>(\r\n  key: string,\r\n  initialValue: InitialValue<T>,\r\n  options: UseSessionStorageOptions<T> = {}\r\n): UseSessionStorageReturn<T> {\r\n  const {\r\n    serializer = JSON.stringify,\r\n    deserializer = JSON.parse,\r\n    onError,\r\n  } = options;\r\n\r\n  // Store options in refs for stable references and access to latest values\r\n  const serializerRef = useRef(serializer);\r\n  const deserializerRef = useRef(deserializer);\r\n  const onErrorRef = useRef(onError);\r\n  serializerRef.current = serializer;\r\n  deserializerRef.current = deserializer;\r\n  onErrorRef.current = onError;\r\n\r\n  // Store initialValue in ref for use in removeValue\r\n  const initialValueRef = useRef(initialValue);\r\n  initialValueRef.current = initialValue;\r\n\r\n  // SSR check\r\n  const isClient = typeof window !== \"undefined\";\r\n\r\n  // Lazy initialization with sessionStorage read\r\n  const [storedValue, setStoredValue] = useState<T>(() => {\r\n    if (!isClient) {\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n\r\n    try {\r\n      const item = window.sessionStorage.getItem(key);\r\n      if (item !== null) {\r\n        return deserializerRef.current(item);\r\n      }\r\n      return resolveInitialValue(initialValue);\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n      return resolveInitialValue(initialValue);\r\n    }\r\n  });\r\n\r\n  // Store current value in ref for stable setValue reference\r\n  const storedValueRef = useRef<T>(storedValue);\r\n  storedValueRef.current = storedValue;\r\n\r\n  // setValue - stable reference (only depends on key)\r\n  const setValue = useCallback<React.Dispatch<React.SetStateAction<T>>>(\r\n    (value) => {\r\n      try {\r\n        const currentValue = storedValueRef.current;\r\n        const valueToStore =\r\n          value instanceof Function ? value(currentValue) : value;\r\n\r\n        setStoredValue(valueToStore);\r\n\r\n        if (typeof window !== \"undefined\") {\r\n          window.sessionStorage.setItem(\r\n            key,\r\n            serializerRef.current(valueToStore)\r\n          );\r\n        }\r\n      } catch (error) {\r\n        onErrorRef.current?.(error as Error);\r\n      }\r\n    },\r\n    [key]\r\n  );\r\n\r\n  // removeValue - stable reference\r\n  const removeValue = useCallback(() => {\r\n    try {\r\n      const initial = resolveInitialValue(initialValueRef.current);\r\n      setStoredValue(initial);\r\n\r\n      if (typeof window !== \"undefined\") {\r\n        window.sessionStorage.removeItem(key);\r\n      }\r\n    } catch (error) {\r\n      onErrorRef.current?.(error as Error);\r\n    }\r\n  }, [key]);\r\n\r\n  // Re-read value when key changes\r\n  useEffect(() => {\r\n    if (!isClient) {\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const item = window.sessionStorage.getItem(key);\r\n      if (item !== null) {\r\n        setStoredValue(deserializerRef.current(item));\r\n      } else {\r\n        setStoredValue(resolveInitialValue(initialValueRef.current));\r\n      }\r\n    } catch {\r\n      setStoredValue(resolveInitialValue(initialValueRef.current));\r\n    }\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [key]);\r\n\r\n  return [storedValue, setValue, removeValue] as const;\r\n}\r\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":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@usefy/use-session-storage",
+  "version": "0.0.2",
+  "description": "A React hook for persisting state in sessionStorage",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "jsdom": "^27.3.0",
+    "react": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geon0529/usefy.git",
+    "directory": "packages/use-session-storage"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "hooks",
+    "session-storage",
+    "sessionStorage",
+    "state",
+    "persistence"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}