@himanshu-sorathiya/react-kit 1.0.26 → 1.0.27

package/dist/index.d.ts

@@ -816,43 +816,295 @@ export interface UseSortReturn<T> {
 	getSortIndex: (id: string) => number | undefined;
 }
 export declare function useSort<T>(data?: T[], initialSorts?: SortState): UseSortReturn<T>;
+/**
+ * Defines how a value of type `T` is converted to and from the string
+ * format that `localStorage`/`sessionStorage` can actually store — the Web
+ * Storage API only ever stores strings.
+ *
+ * Implement this to store types the default JSON-based serializer can't
+ * round-trip faithfully, e.g. `Map`, `Set`, `Date`, or `bigint` — see
+ * `mapSerializer`, `setSerializer`, `dateSerializer`, and
+ * `bigIntSerializer` in `serializers.ts` for ready-made ones.
+ *
+ * @typeParam T - The in-memory value type this serializer handles.
+ */
 export interface StorageSerializer<T> {
+	/** Converts an in-memory value into the string that gets stored. */
 	serialize: (value: T) => string;
+	/**
+	 * Converts a stored string back into an in-memory value.
+	 *
+	 * @throws If the raw string can't be converted back into `T`. The hook
+	 * catches this, falls back to `initialValue`, and reports the error —
+	 * see `onError` on {@link BaseStorageOptions}.
+	 */
 	deserialize: (raw: string) => T;
 }
+/**
+ * Options shared by `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
 export interface BaseStorageOptions<T> {
+	/**
+	 * Custom (de)serializer for values that don't round-trip through
+	 * `JSON.stringify`/`JSON.parse` cleanly.
+	 *
+	 * @defaultValue `defaultSerializer` (plain `JSON.stringify`/`JSON.parse`)
+	 */
 	serializer?: StorageSerializer<T>;
+	/**
+	 * Whether to synchronously read the existing stored value on mount.
+	 *
+	 * - `true` (default): `value` reflects storage from the very first
+	 *   render it's allowed to (see the SSR note below).
+	 * - `false`: `value` starts as `undefined` and only reflects storage
+	 *   once `isHydrated` becomes `true`, one render after mount. Use this
+	 *   if you'd rather render a loading/skeleton state than briefly show a
+	 *   value that might change right after.
+	 *
+	 * Either way, on the server — and during the client's hydration render
+	 * — `value` is always `initialValue`. This option only affects timing
+	 * on the client, after that point.
+	 *
+	 * @defaultValue `true`
+	 */
 	initializeWithValue?: boolean;
+	/**
+	 * Whether other instances of this hook watching the *same key* in the
+	 * *same tab* stay in sync with each other. Implemented via a
+	 * `CustomEvent` dispatched on `window` — the browser's native `storage`
+	 * event never fires in the tab that made the change, so without this,
+	 * two components reading the same key in one tab would drift apart.
+	 *
+	 * @defaultValue `true`
+	 */
 	sameInstanceSync?: boolean;
+	/**
+	 * Called whenever the hook hits an unexpected condition: a failed
+	 * read, a failed write, a failed cross-instance deserialize, or an
+	 * attempt to change the storage key at runtime. Fires in every
+	 * environment, including production — use this for telemetry/error
+	 * reporting.
+	 *
+	 * This is *not* a replacement for the dev-only `console.warn` the hook
+	 * also emits for the same conditions (visible when
+	 * `process.env.NODE_ENV !== "production"`) — both fire independently.
+	 */
+	onError?: (error: Error) => void;
 }
+/**
+ * Payload carried by the same-tab `CustomEvent` used for
+ * {@link BaseStorageOptions.sameInstanceSync}. Internal — not part of the
+ * public hook API, but exported so `useStorageEngine.ts` can import it.
+ */
 export interface StorageCustomEventDetail {
+	/** The new serialized value, or `null` if the key was removed. */
 	value: string | null;
+	/**
+	 * A per-hook-instance identifier, used so an instance can recognize —
+	 * and ignore — the event it just dispatched itself.
+	 */
 	instanceId: symbol;
 }
-export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
-	crossInstanceSync?: boolean;
-}
-export interface UseLocalStorageReturn<T> {
+/**
+ * The shape returned by {@link useStorageEngine} — and, re-exported, by
+ * both `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+interface UseStorageEngineReturn<T> {
+	/**
+	 * The current value.
+	 *
+	 * - `undefined` if nothing is stored yet and no `initialValue` was
+	 *   given, or — when `initializeWithValue: false` — before hydration
+	 *   completes.
+	 * - On the server, and during the client's hydration render, this is
+	 *   always `initialValue`: real storage can only be read client-side,
+	 *   and reading it any earlier would produce a hydration mismatch.
+	 */
 	value: T | undefined;
+	/**
+	 * Writes a new value to storage. Accepts either the value directly, or
+	 * an updater function that receives the current value and returns the
+	 * next one — the same convention as `useState`'s setter.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	/**
+	 * Removes the key from storage entirely and resets `value` back to
+	 * whatever `initialValue` was passed to the hook.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	removeValue: () => void;
+	/**
+	 * `true` once the client has mounted and the hook has settled on its
+	 * real (non-server-snapshot) value. Useful for showing a loading state
+	 * instead of a value that might change the instant hydration finishes.
+	 */
 	isHydrated: boolean;
+	/**
+	 * The most recent error the hook encountered — a failed read, write,
+	 * or cross-instance sync, or an attempted key change — or `null` if
+	 * nothing has gone wrong (or an error was cleared by a subsequent
+	 * successful write/remove). See `onError` on {@link BaseStorageOptions}
+	 * for an imperative alternative to reading this reactively.
+	 */
 	error: Error | null;
 }
-export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
-export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
-export interface UseSessionStorageReturn<T> {
-	value: T | undefined;
-	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
-	removeValue: () => void;
-	isHydrated: boolean;
-	error: Error | null;
+/**
+ * Options accepted by `useLocalStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	/**
+	 * Whether this hook instance should sync with the same key changing in
+	 * *other tabs/windows* on the same origin, via the browser's native
+	 * `storage` event. Has no `sessionStorage` equivalent — sessionStorage
+	 * isn't shared across tabs, so there's nothing to sync in that case.
+	 *
+	 * @defaultValue `true`
+	 */
+	crossInstanceSync?: boolean;
 }
-export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+/**
+ * Reads and writes a `localStorage` key, kept in sync with React state.
+ *
+ * - Persists across page reloads and browser restarts (unlike
+ *   `useSessionStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseLocalStorageOptions.sameInstanceSync} — and
+ *   with other tabs/windows on the same origin — see
+ *   {@link UseLocalStorageOptions.crossInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `localStorage` key to read and write. Changing this on
+ * a later render isn't supported; the hook warns (dev console + `onError`)
+ * and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseLocalStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * const { value: theme, setValue: setTheme } = useLocalStorage<"light" | "dark">("theme", "light");
+ *
+ * <button onClick={() => setTheme(prev => (prev === "light" ? "dark" : "light"))}>
+ *   Toggle theme
+ * </button>
+ * ```
+ *
+ * @example
+ * With a custom serializer and error reporting:
+ * ```tsx
+ * const { value, setValue, error } = useLocalStorage("lastSeen", new Date(), {
+ *   serializer: dateSerializer,
+ *   onError: (err) => reportToErrorTracker(err),
+ * });
+ * ```
+ */
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * Options accepted by `useSessionStorage`. Identical to
+ * `BaseStorageOptions` — unlike `UseLocalStorageOptions`, there's no
+ * `crossInstanceSync` option here, since sessionStorage isn't shared
+ * across tabs in the first place.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+/**
+ * Reads and writes a `sessionStorage` key, kept in sync with React state.
+ *
+ * - Scoped to the current tab: cleared when the tab closes, and not
+ *   shared with other tabs (unlike `useLocalStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseSessionStorageOptions.sameInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `sessionStorage` key to read and write. Changing this
+ * on a later render isn't supported; the hook warns (dev console +
+ * `onError`) and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseSessionStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * ```tsx
+ * const { value: draft, setValue: setDraft } = useSessionStorage("draft-comment", "");
+ *
+ * <textarea value={draft ?? ""} onChange={(e) => setDraft(e.target.value)} />
+ * ```
+ */
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * The default serializer used when no `serializer` option is passed to
+ * `useLocalStorage`/`useSessionStorage`. Plain `JSON.stringify`/
+ * `JSON.parse` — works for any JSON-safe value (objects, arrays, strings,
+ * numbers, booleans, `null`), but not `Map`, `Set`, `Date`, `bigint`, or
+ * `undefined` (see the other serializers below for those).
+ */
 export declare const defaultSerializer: StorageSerializer<unknown>;
+/**
+ * Serializer for `Map` values. `JSON.stringify` can't handle `Map`
+ * directly, so this round-trips it via an array of `[key, value]` entries.
+ *
+ * @typeParam K - The map's key type.
+ * @typeParam V - The map's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("tags", new Map<string, number>(), {
+ *   serializer: mapSerializer<string, number>(),
+ * });
+ * ```
+ */
 export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+/**
+ * Serializer for `Set` values, round-tripped via a plain array.
+ *
+ * @typeParam V - The set's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("selectedIds", new Set<string>(), {
+ *   serializer: setSerializer<string>(),
+ * });
+ * ```
+ */
 export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+/**
+ * Serializer for `Date` values, stored as an ISO 8601 string
+ * (`Date.prototype.toISOString`).
+ *
+ * @throws During `deserialize`, if the stored string isn't a valid date —
+ * caught by the hook, which falls back to `initialValue` and reports the
+ * error via `onError`/the dev console warning.
+ */
 export declare const dateSerializer: StorageSerializer<Date>;
+/**
+ * Serializer for `bigint` values. `JSON.stringify` throws on `bigint`
+ * values, so this stores them as a plain decimal string instead.
+ *
+ * @throws During `deserialize`, if the stored string can't be converted to
+ * a `bigint` — caught by the hook, which falls back to `initialValue` and
+ * reports the error via `onError`/the dev console warning.
+ */
 export declare const bigIntSerializer: StorageSerializer<bigint>;
 export interface FuzzyHighlighterProps {
 	text: string;
@@ -948,4 +1200,9 @@ export declare function useVisibility<T = unknown>(options?: {
 	initialVisibleIds?: VisibilityId[];
 }): UseVisibilityReturn<T>;
 
+export {
+	UseStorageEngineReturn as UseLocalStorageReturn,
+	UseStorageEngineReturn as UseSessionStorageReturn,
+};
+
 export {};

package/dist/storage.d.ts

@@ -1,42 +1,299 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+ * Defines how a value of type `T` is converted to and from the string
+ * format that `localStorage`/`sessionStorage` can actually store — the Web
+ * Storage API only ever stores strings.
+ *
+ * Implement this to store types the default JSON-based serializer can't
+ * round-trip faithfully, e.g. `Map`, `Set`, `Date`, or `bigint` — see
+ * `mapSerializer`, `setSerializer`, `dateSerializer`, and
+ * `bigIntSerializer` in `serializers.ts` for ready-made ones.
+ *
+ * @typeParam T - The in-memory value type this serializer handles.
+ */
 export interface StorageSerializer<T> {
+	/** Converts an in-memory value into the string that gets stored. */
 	serialize: (value: T) => string;
+	/**
+	 * Converts a stored string back into an in-memory value.
+	 *
+	 * @throws If the raw string can't be converted back into `T`. The hook
+	 * catches this, falls back to `initialValue`, and reports the error —
+	 * see `onError` on {@link BaseStorageOptions}.
+	 */
 	deserialize: (raw: string) => T;
 }
+/**
+ * Options shared by `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
 export interface BaseStorageOptions<T> {
+	/**
+	 * Custom (de)serializer for values that don't round-trip through
+	 * `JSON.stringify`/`JSON.parse` cleanly.
+	 *
+	 * @defaultValue `defaultSerializer` (plain `JSON.stringify`/`JSON.parse`)
+	 */
 	serializer?: StorageSerializer<T>;
+	/**
+	 * Whether to synchronously read the existing stored value on mount.
+	 *
+	 * - `true` (default): `value` reflects storage from the very first
+	 *   render it's allowed to (see the SSR note below).
+	 * - `false`: `value` starts as `undefined` and only reflects storage
+	 *   once `isHydrated` becomes `true`, one render after mount. Use this
+	 *   if you'd rather render a loading/skeleton state than briefly show a
+	 *   value that might change right after.
+	 *
+	 * Either way, on the server — and during the client's hydration render
+	 * — `value` is always `initialValue`. This option only affects timing
+	 * on the client, after that point.
+	 *
+	 * @defaultValue `true`
+	 */
 	initializeWithValue?: boolean;
+	/**
+	 * Whether other instances of this hook watching the *same key* in the
+	 * *same tab* stay in sync with each other. Implemented via a
+	 * `CustomEvent` dispatched on `window` — the browser's native `storage`
+	 * event never fires in the tab that made the change, so without this,
+	 * two components reading the same key in one tab would drift apart.
+	 *
+	 * @defaultValue `true`
+	 */
 	sameInstanceSync?: boolean;
+	/**
+	 * Called whenever the hook hits an unexpected condition: a failed
+	 * read, a failed write, a failed cross-instance deserialize, or an
+	 * attempt to change the storage key at runtime. Fires in every
+	 * environment, including production — use this for telemetry/error
+	 * reporting.
+	 *
+	 * This is *not* a replacement for the dev-only `console.warn` the hook
+	 * also emits for the same conditions (visible when
+	 * `process.env.NODE_ENV !== "production"`) — both fire independently.
+	 */
+	onError?: (error: Error) => void;
 }
+/**
+ * Payload carried by the same-tab `CustomEvent` used for
+ * {@link BaseStorageOptions.sameInstanceSync}. Internal — not part of the
+ * public hook API, but exported so `useStorageEngine.ts` can import it.
+ */
 export interface StorageCustomEventDetail {
+	/** The new serialized value, or `null` if the key was removed. */
 	value: string | null;
+	/**
+	 * A per-hook-instance identifier, used so an instance can recognize —
+	 * and ignore — the event it just dispatched itself.
+	 */
 	instanceId: symbol;
 }
-export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
-	crossInstanceSync?: boolean;
-}
-export interface UseLocalStorageReturn<T> {
+/**
+ * The shape returned by {@link useStorageEngine} — and, re-exported, by
+ * both `useLocalStorage` and `useSessionStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+interface UseStorageEngineReturn<T> {
+	/**
+	 * The current value.
+	 *
+	 * - `undefined` if nothing is stored yet and no `initialValue` was
+	 *   given, or — when `initializeWithValue: false` — before hydration
+	 *   completes.
+	 * - On the server, and during the client's hydration render, this is
+	 *   always `initialValue`: real storage can only be read client-side,
+	 *   and reading it any earlier would produce a hydration mismatch.
+	 */
 	value: T | undefined;
+	/**
+	 * Writes a new value to storage. Accepts either the value directly, or
+	 * an updater function that receives the current value and returns the
+	 * next one — the same convention as `useState`'s setter.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
+	/**
+	 * Removes the key from storage entirely and resets `value` back to
+	 * whatever `initialValue` was passed to the hook.
+	 *
+	 * A no-op if storage isn't available (SSR, or storage access blocked).
+	 */
 	removeValue: () => void;
+	/**
+	 * `true` once the client has mounted and the hook has settled on its
+	 * real (non-server-snapshot) value. Useful for showing a loading state
+	 * instead of a value that might change the instant hydration finishes.
+	 */
 	isHydrated: boolean;
+	/**
+	 * The most recent error the hook encountered — a failed read, write,
+	 * or cross-instance sync, or an attempted key change — or `null` if
+	 * nothing has gone wrong (or an error was cleared by a subsequent
+	 * successful write/remove). See `onError` on {@link BaseStorageOptions}
+	 * for an imperative alternative to reading this reactively.
+	 */
 	error: Error | null;
 }
-export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>;
-export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
-export interface UseSessionStorageReturn<T> {
-	value: T | undefined;
-	setValue: (valueOrUpdater: T | ((prev: T | undefined) => T)) => void;
-	removeValue: () => void;
-	isHydrated: boolean;
-	error: Error | null;
+/**
+ * Options accepted by `useLocalStorage`.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export interface UseLocalStorageOptions<T> extends BaseStorageOptions<T> {
+	/**
+	 * Whether this hook instance should sync with the same key changing in
+	 * *other tabs/windows* on the same origin, via the browser's native
+	 * `storage` event. Has no `sessionStorage` equivalent — sessionStorage
+	 * isn't shared across tabs, so there's nothing to sync in that case.
+	 *
+	 * @defaultValue `true`
+	 */
+	crossInstanceSync?: boolean;
 }
-export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseSessionStorageReturn<T>;
+/**
+ * Reads and writes a `localStorage` key, kept in sync with React state.
+ *
+ * - Persists across page reloads and browser restarts (unlike
+ *   `useSessionStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseLocalStorageOptions.sameInstanceSync} — and
+ *   with other tabs/windows on the same origin — see
+ *   {@link UseLocalStorageOptions.crossInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `localStorage` key to read and write. Changing this on
+ * a later render isn't supported; the hook warns (dev console + `onError`)
+ * and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseLocalStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * const { value: theme, setValue: setTheme } = useLocalStorage<"light" | "dark">("theme", "light");
+ *
+ * <button onClick={() => setTheme(prev => (prev === "light" ? "dark" : "light"))}>
+ *   Toggle theme
+ * </button>
+ * ```
+ *
+ * @example
+ * With a custom serializer and error reporting:
+ * ```tsx
+ * const { value, setValue, error } = useLocalStorage("lastSeen", new Date(), {
+ *   serializer: dateSerializer,
+ *   onError: (err) => reportToErrorTracker(err),
+ * });
+ * ```
+ */
+export declare function useLocalStorage<T = unknown>(key: string, initialValue?: T, options?: UseLocalStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * Options accepted by `useSessionStorage`. Identical to
+ * `BaseStorageOptions` — unlike `UseLocalStorageOptions`, there's no
+ * `crossInstanceSync` option here, since sessionStorage isn't shared
+ * across tabs in the first place.
+ *
+ * @typeParam T - The type of value being stored.
+ */
+export type UseSessionStorageOptions<T> = BaseStorageOptions<T>;
+/**
+ * Reads and writes a `sessionStorage` key, kept in sync with React state.
+ *
+ * - Scoped to the current tab: cleared when the tab closes, and not
+ *   shared with other tabs (unlike `useLocalStorage`).
+ * - Stays in sync with every component in the current tab watching the
+ *   same key — see {@link UseSessionStorageOptions.sameInstanceSync}.
+ * - Safe under SSR: on the server, and during the client's hydration
+ *   render, `value` is always `initialValue`. The real stored value is
+ *   only read client-side, immediately after hydration.
+ *
+ * @typeParam T - The type of value being stored. Defaults to `unknown` if
+ * omitted — pass an explicit type argument for anything beyond ad-hoc use.
+ * @param key - The `sessionStorage` key to read and write. Changing this
+ * on a later render isn't supported; the hook warns (dev console +
+ * `onError`) and keeps using the original key if you do.
+ * @param initialValue - Used when nothing is stored yet, as the value
+ * shown before hydration completes, and as what `removeValue` resets to.
+ * @param options - See {@link UseSessionStorageOptions}.
+ * @returns `{ value, setValue, removeValue, isHydrated, error }`.
+ *
+ * @example
+ * ```tsx
+ * const { value: draft, setValue: setDraft } = useSessionStorage("draft-comment", "");
+ *
+ * <textarea value={draft ?? ""} onChange={(e) => setDraft(e.target.value)} />
+ * ```
+ */
+export declare function useSessionStorage<T = unknown>(key: string, initialValue?: T, options?: UseSessionStorageOptions<T>): UseStorageEngineReturn<T>;
+/**
+ * The default serializer used when no `serializer` option is passed to
+ * `useLocalStorage`/`useSessionStorage`. Plain `JSON.stringify`/
+ * `JSON.parse` — works for any JSON-safe value (objects, arrays, strings,
+ * numbers, booleans, `null`), but not `Map`, `Set`, `Date`, `bigint`, or
+ * `undefined` (see the other serializers below for those).
+ */
 export declare const defaultSerializer: StorageSerializer<unknown>;
+/**
+ * Serializer for `Map` values. `JSON.stringify` can't handle `Map`
+ * directly, so this round-trips it via an array of `[key, value]` entries.
+ *
+ * @typeParam K - The map's key type.
+ * @typeParam V - The map's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("tags", new Map<string, number>(), {
+ *   serializer: mapSerializer<string, number>(),
+ * });
+ * ```
+ */
 export declare function mapSerializer<K, V>(): StorageSerializer<Map<K, V>>;
+/**
+ * Serializer for `Set` values, round-tripped via a plain array.
+ *
+ * @typeParam V - The set's value type.
+ *
+ * @example
+ * ```ts
+ * useLocalStorage("selectedIds", new Set<string>(), {
+ *   serializer: setSerializer<string>(),
+ * });
+ * ```
+ */
 export declare function setSerializer<V>(): StorageSerializer<Set<V>>;
+/**
+ * Serializer for `Date` values, stored as an ISO 8601 string
+ * (`Date.prototype.toISOString`).
+ *
+ * @throws During `deserialize`, if the stored string isn't a valid date —
+ * caught by the hook, which falls back to `initialValue` and reports the
+ * error via `onError`/the dev console warning.
+ */
 export declare const dateSerializer: StorageSerializer<Date>;
+/**
+ * Serializer for `bigint` values. `JSON.stringify` throws on `bigint`
+ * values, so this stores them as a plain decimal string instead.
+ *
+ * @throws During `deserialize`, if the stored string can't be converted to
+ * a `bigint` — caught by the hook, which falls back to `initialValue` and
+ * reports the error via `onError`/the dev console warning.
+ */
 export declare const bigIntSerializer: StorageSerializer<bigint>;
 
+export {
+	UseStorageEngineReturn as UseLocalStorageReturn,
+	UseStorageEngineReturn as UseSessionStorageReturn,
+};
+
 export {};

package/dist/storage2.js

@@ -1,30 +1,41 @@
-import { t as e } from "./useEventListener.js";
-import { useCallback as t, useEffect as n, useRef as r, useState as i } from "react";
+import { useCallback as e, useEffect as t, useRef as n, useState as r, useSyncExternalStore as i } from "react";
+//#region src/shared/storageShared/getStorage.ts
+function a(e) {
+	return () => {
+		if (typeof window > "u") return null;
+		try {
+			return window[e];
+		} catch {
+			return null;
+		}
+	};
+}
+//#endregion
 //#region src/shared/storageShared/serializers.ts
-var a = {
+var o = {
 	serialize: (e) => JSON.stringify(e),
 	deserialize: (e) => JSON.parse(e)
 };
-function o() {
+function s() {
 	return {
 		serialize: (e) => JSON.stringify(Array.from(e.entries())),
 		deserialize: (e) => new Map(JSON.parse(e))
 	};
 }
-function s() {
+function c() {
 	return {
 		serialize: (e) => JSON.stringify(Array.from(e.values())),
 		deserialize: (e) => new Set(JSON.parse(e))
 	};
 }
-var c = {
+var l = {
 	serialize: (e) => e.toISOString(),
 	deserialize: (e) => {
 		let t = new Date(e);
 		if (isNaN(t.getTime())) throw Error(`[react-kit] dateSerializer: invalid date string "${e}"`);
 		return t;
 	}
-}, l = {
+}, u = {
 	serialize: (e) => e.toString(),
 	deserialize: (e) => {
 		try {
@@ -33,229 +44,155 @@ var c = {
 			throw Error(`[react-kit] bigIntSerializer: cannot convert "${e}" to bigint`);
 		}
 	}
-}, u = "react-kit:use-local-storage";
-//#endregion
-//#region src/storage/useLocalStorage/utils.ts
-function d() {
-	if (typeof window > "u") return null;
+}, d = globalThis.process?.env?.NODE_ENV !== "production";
+function f(e, t, n) {
 	try {
-		return window.localStorage;
+		return t.deserialize(e);
 	} catch {
-		return null;
+		return n;
 	}
 }
-function f(e, t, n, r) {
-	try {
-		let i = e.getItem(t);
-		return i === null ? {
-			value: n,
-			error: null
-		} : {
-			value: r.deserialize(i),
-			error: null
+function p(a, s, c, l = {}) {
+	let { serializer: u = o, initializeWithValue: p = !0, sameInstanceSync: m = !0, crossInstanceSync: h = !0, onError: g } = l, [_] = r(() => s), v = s !== _, [y] = r(() => Symbol()), b = n(u);
+	t(() => {
+		b.current = u;
+	}, [u]);
+	let x = n(c);
+	t(() => {
+		x.current = c;
+	}, [c]);
+	let S = n(g);
+	t(() => {
+		S.current = g;
+	}, [g]);
+	let [C, w] = r(null), T = e((e, t) => {
+		d && console.warn(`[${a.hookLabel}] ${e}:`, t.message), S.current?.(t), w(t);
+	}, [a.hookLabel]);
+	t(() => {
+		v && T("Ignoring key change", /* @__PURE__ */ Error(`Changing the storage key at runtime is not supported. Still using original key: "${_}". Received new key: "${s}".`));
+	}, [
+		s,
+		v,
+		_,
+		T
+	]);
+	let E = n({
+		raw: null,
+		parsed: c
+	}), D = n(null), O = e(() => {
+		let e = a.getStorage();
+		if (!e) return x.current;
+		let t = e.getItem(_);
+		if (E.current.raw === t) return E.current.parsed;
+		let n = t === null ? x.current : f(t, b.current, x.current);
+		return E.current = {
+			raw: t,
+			parsed: n
+		}, n;
+	}, [_]), k = e(() => x.current, []), A = i(e((e) => {
+		if (D.current = e, typeof window > "u") return () => {
+			D.current = null;
 		};
-	} catch (e) {
-		return {
-			value: n,
-			error: e instanceof Error ? e : Error(String(e))
+		let t = new AbortController();
+		return h && a.nativeStorageEventSupported && window.addEventListener("storage", (t) => {
+			t.storageArea === a.getStorage() && (t.key !== null && t.key !== _ || e());
+		}, { signal: t.signal }), m && window.addEventListener(`${a.customEventName}:${_}`, (t) => {
+			t.detail.instanceId !== y && e();
+		}, { signal: t.signal }), () => {
+			t.abort(), D.current = null;
 		};
-	}
-}
-function p(e, t, n) {
-	let r = {
-		value: t,
-		instanceId: n
-	}, i = new CustomEvent(`${u}:${e}`, { detail: r });
-	window.dispatchEvent(i);
-}
-//#endregion
-//#region src/storage/useLocalStorage/useLocalStorage.ts
-function m(o, s, c = {}) {
-	let { serializer: l = a, initializeWithValue: m = !0, sameInstanceSync: h = !0, crossInstanceSync: g = !0 } = c, [_] = i(() => o), v = r(_), y = o !== _, b = `${u}:${_}`, x = r(Symbol()), S = r(l);
-	n(() => {
-		S.current = l;
-	}, [l]);
-	let [C, w] = i(() => {
-		if (!m) return;
-		let e = d();
-		if (!e) return s;
-		let { value: t } = f(e, o, s, l);
-		return t;
-	}), T = r(C);
-	n(() => {
-		T.current = C;
-	}, [C]);
-	let [E, D] = i(m && typeof window < "u"), [O, k] = i(null);
-	n(() => {
-		if (!y) return;
-		let e = /* @__PURE__ */ Error(`[react-kit:use-local-storage] Changing the storage key at runtime is not supported. Still using original key: "${v.current}". Received new key: "${o}".`);
-		console.warn(e.message), k(e);
-	}, [o, y]), n(() => {
-		if (m) return;
-		let e = d(), { value: t, error: n } = e === null ? {
-			value: s,
-			error: null
-		} : f(e, v.current, s, S.current);
-		n && (console.warn(`[react-kit:use-local-storage] Failed to read key "${v.current}" from localStorage:`, n.message), k(n)), w(t), D(!0);
-	}, [m]);
-	let A = t((e) => {
-		let t = d();
-		if (!t) return;
-		let n = T.current, r = typeof e == "function" ? e(n) : e;
-		try {
-			let e = S.current.serialize(r);
-			t.setItem(v.current, e), w(r), k(null), h && p(v.current, e, x.current);
+	}, [
+		_,
+		h,
+		m,
+		a,
+		y
+	]), O, k), [j, M] = r(!1);
+	t(() => {
+		M(!0);
+	}, []);
+	let N = p || j ? A : void 0, P = n(void 0);
+	return t(() => {
+		let e = a.getStorage();
+		if (!e) return;
+		let t = e.getItem(_);
+		if (t !== P.current && (P.current = t, t !== null)) try {
+			b.current.deserialize(t);
 		} catch (e) {
-			let t = e instanceof Error ? e : Error(String(e));
-			console.warn(`[react-kit:use-local-storage] Failed to write key "${v.current}" to localStorage:`, t.message), k(t);
+			T(`Failed to read key "${_}"`, e instanceof Error ? e : Error(String(e)));
 		}
-	}, [h]), j = t(() => {
-		let e = d();
-		e && (e.removeItem(v.current), w(s), k(null), h && p(v.current, null, x.current));
-	}, [h]);
-	return e("storage", (e) => {
-		if (g && e.storageArea === d() && e.key === v.current) {
-			if (e.newValue === null) {
-				w(s), k(null);
-				return;
-			}
+	}), {
+		value: N,
+		setValue: e((e) => {
+			let t = a.getStorage();
+			if (!t) return;
+			let n = O(), r = typeof e == "function" ? e(n) : e;
 			try {
-				let t = S.current.deserialize(e.newValue);
-				w(t), k(null);
+				let e = b.current.serialize(r);
+				if (t.setItem(_, e), E.current = {
+					raw: e,
+					parsed: r
+				}, P.current = e, w(null), D.current?.(), m) {
+					let t = {
+						value: e,
+						instanceId: y
+					};
+					window.dispatchEvent(new CustomEvent(`${a.customEventName}:${_}`, { detail: t }));
+				}
 			} catch (e) {
-				let t = e instanceof Error ? e : Error(String(e));
-				console.warn(`[react-kit:use-local-storage] Failed to deserialize cross-tab update for key "${v.current}":`, t.message), w(s), k(t);
-			}
-		}
-	}), e(b, (e) => {
-		if (!h) return;
-		let t = e.detail;
-		if (t.instanceId !== x.current) {
-			if (t.value === null) {
-				w(s), k(null);
-				return;
+				T(`Failed to write key "${_}"`, e instanceof Error ? e : Error(String(e)));
 			}
-			try {
-				let e = S.current.deserialize(t.value);
-				w(e), k(null);
-			} catch (e) {
-				let t = e instanceof Error ? e : Error(String(e));
-				console.warn(`[react-kit:use-local-storage] Failed to deserialize same-tab update for key "${v.current}":`, t.message), w(s), k(t);
+		}, [
+			a,
+			_,
+			m,
+			O,
+			T,
+			y
+		]),
+		removeValue: e(() => {
+			let e = a.getStorage();
+			if (e && (e.removeItem(_), E.current = {
+				raw: null,
+				parsed: x.current
+			}, P.current = null, w(null), D.current?.(), m)) {
+				let e = {
+					value: null,
+					instanceId: y
+				};
+				window.dispatchEvent(new CustomEvent(`${a.customEventName}:${_}`, { detail: e }));
 			}
-		}
-	}, { target: typeof window > "u" ? null : window }), {
-		value: C,
-		setValue: A,
-		removeValue: j,
-		isHydrated: E,
-		error: O
+		}, [
+			a,
+			_,
+			m,
+			y
+		]),
+		isHydrated: j,
+		error: C
 	};
 }
 //#endregion
-//#region src/storage/useSessionStorage/constants.ts
-var h = "react-kit:use-session-storage";
-//#endregion
-//#region src/storage/useSessionStorage/utils.ts
-function g() {
-	if (typeof window > "u") return null;
-	try {
-		return window.sessionStorage;
-	} catch {
-		return null;
-	}
-}
-function _(e, t, n, r) {
-	try {
-		let i = e.getItem(t);
-		return i === null ? {
-			value: n,
-			error: null
-		} : {
-			value: r.deserialize(i),
-			error: null
-		};
-	} catch (e) {
-		return {
-			value: n,
-			error: e instanceof Error ? e : Error(String(e))
-		};
-	}
-}
-function v(e, t, n) {
-	let r = {
-		value: t,
-		instanceId: n
-	}, i = new CustomEvent(`${h}:${e}`, { detail: r });
-	window.dispatchEvent(i);
+//#region src/storage/useLocalStorage/useLocalStorage.ts
+var m = {
+	hookLabel: "react-kit:use-local-storage",
+	getStorage: a("localStorage"),
+	customEventName: "react-kit:use-local-storage",
+	nativeStorageEventSupported: !0
+};
+function h(e, t, n = {}) {
+	return p(m, e, t, n);
 }
 //#endregion
 //#region src/storage/useSessionStorage/useSessionStorage.ts
-function y(o, s, c = {}) {
-	let { serializer: l = a, initializeWithValue: u = !0, sameInstanceSync: d = !0 } = c, [f] = i(() => o), p = r(f), m = o !== f, y = `${h}:${f}`, b = r(Symbol()), x = r(l);
-	n(() => {
-		x.current = l;
-	}, [l]);
-	let [S, C] = i(() => {
-		if (!u) return;
-		let e = g();
-		if (!e) return s;
-		let { value: t } = _(e, o, s, l);
-		return t;
-	}), w = r(S);
-	n(() => {
-		w.current = S;
-	}, [S]);
-	let [T, E] = i(u && typeof window < "u"), [D, O] = i(null);
-	n(() => {
-		if (!m) return;
-		let e = /* @__PURE__ */ Error(`[react-kit:use-session-storage] Changing the storage key at runtime is not supported. Still using original key: "${p.current}". Received new key: "${o}".`);
-		console.warn(e.message), O(e);
-	}, [o, m]), n(() => {
-		if (u) return;
-		let e = g(), { value: t, error: n } = e === null ? {
-			value: s,
-			error: null
-		} : _(e, p.current, s, x.current);
-		n && (console.warn(`[react-kit:use-session-storage] Failed to read key "${p.current}" from sessionStorage:`, n.message), O(n)), C(t), E(!0);
-	}, [u]);
-	let k = t((e) => {
-		let t = g();
-		if (!t) return;
-		let n = w.current, r = typeof e == "function" ? e(n) : e;
-		try {
-			let e = x.current.serialize(r);
-			t.setItem(p.current, e), C(r), O(null), d && v(p.current, e, b.current);
-		} catch (e) {
-			let t = e instanceof Error ? e : Error(String(e));
-			console.warn(`[react-kit:use-session-storage] Failed to write key "${p.current}" to sessionStorage:`, t.message), O(t);
-		}
-	}, [d]), A = t(() => {
-		let e = g();
-		e && (e.removeItem(p.current), C(s), O(null), d && v(p.current, null, b.current));
-	}, [d]);
-	return e(y, (e) => {
-		if (!d) return;
-		let t = e.detail;
-		if (t.instanceId !== b.current) {
-			if (t.value === null) {
-				C(s), O(null);
-				return;
-			}
-			try {
-				let e = x.current.deserialize(t.value);
-				C(e), O(null);
-			} catch (e) {
-				let t = e instanceof Error ? e : Error(String(e));
-				console.warn(`[react-kit:use-session-storage] Failed to deserialize same-tab update for key "${p.current}":`, t.message), C(s), O(t);
-			}
-		}
-	}, { target: typeof window > "u" ? null : window }), {
-		value: S,
-		setValue: k,
-		removeValue: A,
-		isHydrated: T,
-		error: D
-	};
+var g = {
+	hookLabel: "react-kit:use-session-storage",
+	getStorage: a("sessionStorage"),
+	customEventName: "react-kit:use-session-storage",
+	nativeStorageEventSupported: !1
+};
+function _(e, t, n = {}) {
+	return p(g, e, t, n);
 }
 //#endregion
-export { a, c as i, m as n, o, l as r, s, y as t };
+export { o as a, l as i, h as n, s as o, u as r, c as s, _ as t };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@himanshu-sorathiya/react-kit",
-	"version": "1.0.26",
+	"version": "1.0.27",
 	"description": "An opinionated collection of react hooks, and reusable UI components.",
 	"type": "module",
 	"module": "./dist/index.js",