@himanshu-sorathiya/react-kit 1.0.26 → 1.0.28

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 {};