@akb2/react-use-local-storage 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# react-use-local-storage
+
+A React state hook backed by `localStorage`, built on `useSyncExternalStore`. Read and update values by key, subscribe to changes, and access storage outside React components.
+
+## Installation
+
+```bash
+pnpm add react-use-local-storage
+```
+
+Declared peer dependencies: `react@^18.3.1` and `@akb2/types-tools@^1.3.0`. The current React peer dependency range does not include React 19.
+
+The package provides ESM, CommonJS, and TypeScript declarations.
+
+## Quick start
+
+```tsx
+import { useLocalStorageState } from "react-use-local-storage";
+
+export const Counter = () => {
+  const [count, setCount] = useLocalStorageState<number>("counter");
+
+  return (
+    <button onClick={() => setCount((previous) => (previous ?? 0) + 1)}>
+      Clicks: {count ?? 0}
+    </button>
+  );
+};
+```
+
+The hook returns `undefined` for a missing key. There is no second argument for an initial value. Use `??` to provide a display fallback; this does not write the fallback to storage.
+
+## API
+
+### `useLocalStorageState<T>(key)`
+
+```ts
+const [value, setValue, storageKey] = useLocalStorageState<string>("name");
+```
+
+| Element | Description |
+| --- | --- |
+| `value` | The current value, or `undefined` for a missing key |
+| `setValue` | Writes a value or computes a new value from the previous one |
+| `storageKey` | The key passed to the hook |
+
+```ts
+setValue("Andrew");
+setValue((previous) => `${previous ?? ""}!`);
+```
+
+An updater callback receives the current value from storage. At runtime, this can be `undefined` when the key is missing, so handle that case in the callback. The current setter signature is `Dispatch<SetStateAction<T>>`, which does not reflect this possible `undefined` argument.
+
+Functions cannot be stored as values: a function argument is treated as an updater, and returning a function from that updater throws an error.
+
+### `getLocalStorageValue<T>(key)`
+
+Reads a value without creating a React subscription:
+
+```ts
+import { getLocalStorageValue } from "react-use-local-storage";
+
+const name = getLocalStorageValue<string>("name");
+```
+
+Returns `undefined` for a missing key. The generic type `T` describes the expected value; it does not validate stored data at runtime.
+
+### `setLocalStorageValue<T>(key, valueOrCallback)`
+
+Writes a value and notifies subscribers to that key in the current window:
+
+```ts
+import { setLocalStorageValue } from "react-use-local-storage";
+
+setLocalStorageValue("name", "Andrew");
+setLocalStorageValue<number>("counter", (previous) => (previous ?? 0) + 1);
+```
+
+Writing the same serialized content does not notify subscribers again. Passing `null` removes the value.
+
+### `removeLocalStorageValue(key)`
+
+Removes a value through the library's setter and notifies subscribers if the stored value changes:
+
+```ts
+import { removeLocalStorageValue } from "react-use-local-storage";
+
+removeLocalStorageValue("name");
+```
+
+### `clearLocalStorage()`
+
+```ts
+import { clearLocalStorage } from "react-use-local-storage";
+
+clearLocalStorage();
+```
+
+Clears **all `localStorage` entries for the current origin**, including keys written by other code. It also clears the internal cache and notifies subscribers to keys that existed before the operation.
+
+## Storage format
+
+Values are stored in a JSON wrapper with a `value` property:
+
+```ts
+setLocalStorageValue("name", "Andrew");
+
+localStorage.getItem("name");
+// '{"value":"Andrew"}'
+```
+
+Use JSON-compatible data. For example, `Date` becomes a string during serialization; circular objects and `BigInt` cause serialization errors.
+
+Read values are cached by storage key and raw content. Parsed data is passed through `deepFreeze`. Create new values when updating objects:
+
+```tsx
+import { useLocalStorageState } from "react-use-local-storage";
+
+type Preferences = {
+  theme: "light" | "dark";
+};
+
+export const ThemeButton = () => {
+  const [preferences, setPreferences] =
+    useLocalStorageState<Preferences>("preferences");
+
+  return (
+    <button
+      onClick={() =>
+        setPreferences((previous) => ({ ...previous, theme: "dark" }))
+      }
+    >
+      Theme: {preferences?.theme ?? "light"}
+    </button>
+  );
+};
+```
+
+When reading data written by other code, the getter reads the `.value` property of parsed JSON. If parsing or subsequent processing throws, it returns the original nonempty string. Arbitrary JSON without the wrapper is not the library's storage format.
+
+## Synchronization
+
+- In the current window, use the hook's setter or the library utilities to notify subscribers.
+- External changes are handled through `storage` events for `localStorage`. The handler supports key updates, removal, and storage clearing.
+- Direct calls to `localStorage.setItem()`, `removeItem()`, or `clear()` do not fire a `storage` event in the window that made the change. This subscription does not automatically detect those local writes.
+- Cross-tab synchronization requires the same origin: protocol, host, and port.
+
+When writing directly from another tab, use the `JSON.stringify({ value: ... })` format.
+
+## Server-side rendering
+
+The hook's server snapshot is `undefined`. When `window` is unavailable, reads return `undefined`, and writes and clearing are no-ops. After hydration, React uses the client snapshot from `localStorage`.
+
+Provide a fallback for the initial display, such as `value ?? ""`.
+
+## Limitations
+
+- Accessing or writing to `localStorage` can throw, for example when access is denied or the storage quota is exceeded. The library does not catch these errors.
+- Updates to multiple keys are not transactional.
+- Stored data is not validated against the declared TypeScript type.
+
+## Development
+
+```bash
+pnpm install
+pnpm test
+pnpm run test:watch
+pnpm build
+```
+
+Build output is written to `.dist`: `index.js` for ESM, `index.cjs` for CommonJS, and type declarations.
+
+Additional commands:
+
+```bash
+pnpm lint
+pnpm run lint:fix
+pnpm format
+pnpm run format:check
+```
+
+For package maintainers, publish with:
+
+```bash
+pnpm release
+```
+
+This command builds the package and then publishes it with public access.
+
+## Links
+
+- [Source code](https://github.com/akb2/react-use-local-storage)
+- [Report an issue](https://github.com/akb2/react-use-local-storage/issues)
+
+## License
+
+MPL-2.0. Author: akb2.

package/eslint.config.mjs

@@ -0,0 +1,55 @@
+import js from "@eslint/js";
+import stylistic from "@stylistic/eslint-plugin";
+import { defineConfig } from "eslint/config";
+import reactHooks from "eslint-plugin-react-hooks";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import prettier from "eslint-config-prettier/flat";
+
+export default defineConfig([
+  {
+    ignores: ["**/node_modules/**", "**/dist/**", "**/coverage/**"],
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,jsx,ts,tsx,mts,cts}"],
+    extends: [js.configs.recommended],
+    plugins: { "@stylistic": stylistic },
+    languageOptions: {
+      ecmaVersion: "latest",
+      parserOptions: { ecmaFeatures: { jsx: true } },
+    },
+    rules: {
+      eqeqeq: ["error", "always"],
+      "prefer-const": "error",
+      "no-var": "error",
+      "prefer-arrow-callback": "error",
+      "@stylistic/quotes": ["error", "double", { avoidEscape: true }],
+      "@stylistic/jsx-quotes": ["error", "prefer-double"],
+    },
+  },
+  {
+    files: ["**/*.{ts,tsx,mts,cts}"],
+    extends: [tseslint.configs.recommended],
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", caughtErrorsIgnorePattern: "^_" },
+      ],
+    },
+  },
+  {
+    files: ["{backend,core}/**/*.{js,mjs,cjs,ts,mts,cts}", "**/*.config.{js,mjs,cjs,ts,mts,cts}"],
+    languageOptions: { globals: globals.node },
+  },
+  {
+    files: ["frontend/**/*.{js,jsx,ts,tsx}"],
+    ignores: ["**/*.config.*"],
+    languageOptions: { globals: globals.browser },
+    plugins: { "react-hooks": reactHooks },
+    rules: {
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+    },
+  },
+  prettier,
+]);

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@akb2/react-use-local-storage",
+  "version": "1.0.0",
+  "description": "A state hook with browser's localStorage",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.ts",
+      "import": "./.dist/index.js",
+      "require": "./.dist/index.cjs"
+    }
+  },
+  "keywords": [
+    "react",
+    "localStorage",
+    "hook"
+  ],
+  "author": "akb2",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akb2/react-use-local-storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/akb2/react-use-local-storage/issues"
+  },
+  "license": "MPL-2.0",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.5.1",
+      "onFail": "download"
+    }
+  },
+  "type": "module",
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.2",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
+    "eslint-config-prettier": "^10.1.8",
+    "jsdom": "^30.1.0",
+    "prettier": "^3.9.7",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1"
+  },
+  "dependencies": {
+    "@akb2/types-tools": "^1.3.0",
+    "react": "^18.3.1"
+  },
+  "peerDependencies": {
+    "@akb2/types-tools": "^1.3.0",
+    "react": "^18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@akb2/types-tools": {
+      "optional": false
+    },
+    "react": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --inject ./src/react.inject.ts --dts --format esm,cjs --clean --out-dir .dist --minify",
+    "release": "pnpm run build && pnpm publish --access public",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: false

package/src/hooks/use-local-storage-state.ts

@@ -0,0 +1,33 @@
+import { NotDefinable } from "@akb2/types-tools";
+import { addListenerByKey } from "@utils/add-listener-by-key";
+import { deleteListenerByKey } from "@utils/delete-listener-by-key";
+import { getLocalStorageValue } from "@utils/get-local-storage-value";
+import { setLocalStorageValue } from '@utils/set-local-storage-value';
+import type { Dispatch, SetStateAction } from 'react';
+import { useCallback, useSyncExternalStore } from 'react';
+
+/**
+ * A custom React hook that synchronizes a state variable with local storage.
+ *
+ * @template T The type of the state variable.
+ * @param key The key in local storage to associate with the state variable.
+ * @returns A tuple containing the state variable, a setter function, and the key.
+ */
+export const useLocalStorageState = <T>(key: string): [NotDefinable<T>, Dispatch<SetStateAction<T>>, string] => {
+  const setState = useCallback(setLocalStorageValue.bind(null, key), [key]);
+  const state = useSyncExternalStore(
+    (onStoreChange) => {
+      if (typeof window === 'undefined') {
+        return (): void => {};
+      }
+
+      addListenerByKey(key, onStoreChange);
+
+      return (): void => deleteListenerByKey(key, onStoreChange);
+    },
+    () => getLocalStorageValue<T>(key) as T,
+    () => undefined,
+  );
+
+  return [state, setState, key];
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+export { useLocalStorageState } from './hooks/use-local-storage-state';
+export * from './types/window';
+export { clearLocalStorage } from './utils/clear-local-storage';
+export { getLocalStorageValue } from './utils/get-local-storage-value';
+export { removeLocalStorageValue } from './utils/remove-local-storage-value';
+export { setLocalStorageValue } from './utils/set-local-storage-value';

package/src/react.inject.ts

@@ -0,0 +1,3 @@
+import * as React from 'react';
+
+export { React };

package/src/types/window.ts

@@ -0,0 +1,10 @@
+declare global {
+  interface Window {
+    __AKB2_LOCAL_STORAGE__: {
+      listeners: Map<string, Set<() => void>>;
+      originalData: Map<string, unknown>;
+    }
+  }
+}
+
+export { };

package/src/utils/add-listener-by-key.ts

@@ -0,0 +1,34 @@
+import { isDefined } from "@akb2/types-tools";
+import { getListenersKeysSize } from "@utils/get-listeners-keys-size";
+import { listenExternalStoreEvents } from "@utils/listen-external-store-events";
+
+/**
+ * Adds a listener for changes to a specific key in local storage.
+ *
+ * @param key The key in local storage to listen for changes on.
+ * @param listener The callback function to invoke when the specified key changes.
+ * @returns void
+ */
+export const addListenerByKey = (key: string, listener: () => void): void => {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  if (getListenersKeysSize() === 0) {
+    addEventListener('storage', listenExternalStoreEvents);
+  }
+
+  if(!isDefined(window.__AKB2_LOCAL_STORAGE__)){
+    window.__AKB2_LOCAL_STORAGE__ = { } as typeof window.__AKB2_LOCAL_STORAGE__;
+  }
+
+  if(!isDefined(window.__AKB2_LOCAL_STORAGE__.listeners)){
+    window.__AKB2_LOCAL_STORAGE__.listeners = new Map();
+  }
+
+  if (!window.__AKB2_LOCAL_STORAGE__.listeners.has(key)) {
+    window.__AKB2_LOCAL_STORAGE__.listeners.set(key, new Set());
+  }
+
+  window.__AKB2_LOCAL_STORAGE__.listeners.get(key)!.add(listener);
+};

package/src/utils/clear-local-storage.ts

@@ -0,0 +1,25 @@
+import { isDefined, Nullable } from "@akb2/types-tools";
+
+export const clearLocalStorage = (): void => {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const keys = Array.from(window.__AKB2_LOCAL_STORAGE__?.listeners?.keys()??[]);
+  const currentValues = keys.reduce((acc, key) => {
+    acc.set(key, localStorage.getItem(key) ?? null);
+
+    return acc;
+  }, new Map<string, Nullable<string>>());
+
+  localStorage.clear();
+  window.__AKB2_LOCAL_STORAGE__?.originalData?.clear();
+
+  window.__AKB2_LOCAL_STORAGE__?.listeners?.forEach((listeners, key) => {
+    const currentValue = currentValues.get(key);
+
+    if (isDefined(currentValue)) {
+      listeners.forEach((listener) => listener());
+    }
+  });
+};

package/src/utils/deep-freeze.ts

@@ -0,0 +1,18 @@
+import { isDefined } from "@akb2/types-tools";
+
+/**
+ * Deeply freezes an object, making it immutable.
+ *
+ * @param value - The object to freeze.
+ * @returns The frozen object.
+ */
+export const deepFreeze = <T>(value: T): T => {
+  if (!isDefined(value) || typeof value !== 'object' || Object.isFrozen(value)) {
+    return value;
+  }
+
+  Object.freeze(value);
+  Object.values(value as Record<string, unknown>).forEach(deepFreeze);
+
+  return value;
+};

package/src/utils/delete-listener-by-key.ts

@@ -0,0 +1,29 @@
+import { getListenersKeysSize } from "@utils/get-listeners-keys-size";
+import { listenExternalStoreEvents } from "@utils/listen-external-store-events";
+
+/**
+ * Deletes a listener for changes to a specific key in local storage.
+ *
+ * @param key The key in local storage to stop listening for changes on.
+ * @param listener The callback function to remove.
+ * @returns void
+ */
+export const deleteListenerByKey = (key: string, listener: () => void): void => {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  if (!window.__AKB2_LOCAL_STORAGE__?.listeners?.has(key)) {
+    return;
+  }
+
+  window.__AKB2_LOCAL_STORAGE__.listeners.get(key)!.delete(listener);
+
+  if (window.__AKB2_LOCAL_STORAGE__.listeners.get(key)?.size === 0) {
+    window.__AKB2_LOCAL_STORAGE__.listeners.delete(key);
+  }
+
+  if (getListenersKeysSize() === 0) {
+    removeEventListener('storage', listenExternalStoreEvents);
+  }
+};

package/src/utils/get-listeners-keys-size.ts

@@ -0,0 +1,14 @@
+import { anyToInt } from "@akb2/types-tools";
+
+/**
+ * Gets the number of keys that have listeners in local storage.
+ *
+ * @returns The number of keys with listeners.
+ */
+export const getListenersKeysSize = (): number => {
+  if (typeof window === 'undefined') {
+    return 0;
+  }
+
+  return anyToInt(window.__AKB2_LOCAL_STORAGE__?.listeners?.size);
+}

package/src/utils/get-local-storage-value.ts

@@ -0,0 +1,49 @@
+import { isDefined, NotDefinable } from "@akb2/types-tools";
+import { deepFreeze } from "@utils/deep-freeze";
+import { getOriginalDataStorageKey } from "./get-original-data-storage-key";
+
+/**
+ * Retrieves the value associated with a specific key from local storage.
+ *
+ * @template T The expected type of the value.
+ * @param key The key in local storage to retrieve the value for.
+ * @returns The value associated with the key, or undefined if not found.
+ */
+export const getLocalStorageValue = <T>(key: string): NotDefinable<T> => {
+  if (typeof window === 'undefined') {
+    return undefined;
+  }
+
+  const raw = localStorage.getItem(key);
+
+  if (!isDefined(raw)) {
+    return undefined;
+  }
+
+  if(!isDefined(window.__AKB2_LOCAL_STORAGE__)){
+    window.__AKB2_LOCAL_STORAGE__ = { } as typeof window.__AKB2_LOCAL_STORAGE__;
+  }
+
+  if(!isDefined(window.__AKB2_LOCAL_STORAGE__.originalData)){
+    window.__AKB2_LOCAL_STORAGE__.originalData = new Map();
+  }
+
+  try {
+    const cachedKey = getOriginalDataStorageKey(key, raw);
+    const cachedData = window.__AKB2_LOCAL_STORAGE__.originalData.get(cachedKey);
+
+    if (isDefined(cachedData)) {
+      return cachedData as T;
+    }
+
+    const parsedData = deepFreeze(JSON.parse(raw).value);
+
+    if (isDefined(parsedData)) {
+      window.__AKB2_LOCAL_STORAGE__.originalData.set(cachedKey, parsedData);
+    }
+
+    return parsedData as Readonly<T>;
+  } catch {
+    return raw.length > 0 ? (raw as unknown as T) : undefined;
+  }
+};

package/src/utils/get-original-data-storage-key.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a unique key for storing the original data in local storage.
+ *
+ * @param key The key in local storage.
+ * @param value The value associated with the key.
+ * @returns A unique key for storing the original data.
+ */
+export const getOriginalDataStorageKey = (key: string, value: string): string => `${key}:{${value}}`;

package/src/utils/listen-external-store-events.ts

@@ -0,0 +1,35 @@
+import { isDefined } from "@akb2/types-tools";
+import { getOriginalDataStorageKey } from "@utils/get-original-data-storage-key";
+
+/**
+ * Listens for external changes to the local storage and updates the internal cache and listeners accordingly.
+ *
+ * @param event The storage event triggered by changes to the local storage.
+ * @returns void
+ */
+export const listenExternalStoreEvents = (event: StorageEvent): void => {
+  if (event.storageArea === localStorage) {
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__)){
+      window.__AKB2_LOCAL_STORAGE__ = { } as typeof window.__AKB2_LOCAL_STORAGE__;
+    }
+
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__.listeners)){
+      window.__AKB2_LOCAL_STORAGE__.listeners = new Map();
+    }
+
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__.originalData)){
+      window.__AKB2_LOCAL_STORAGE__.originalData = new Map();
+    }
+
+    if (isDefined(event.key)) {
+      if (isDefined(event.oldValue) && event.oldValue !== event.newValue) {
+        window.__AKB2_LOCAL_STORAGE__.originalData.delete(getOriginalDataStorageKey(event.key, event.oldValue));
+      }
+
+      window.__AKB2_LOCAL_STORAGE__.listeners.get(event.key)?.forEach((listener) => listener());
+    } else {
+      window.__AKB2_LOCAL_STORAGE__.originalData.clear();
+      window.__AKB2_LOCAL_STORAGE__.listeners.forEach((listeners) => listeners.forEach((listener) => listener()));
+    }
+  }
+};

package/src/utils/remove-local-storage-value.ts

@@ -0,0 +1,3 @@
+import { setLocalStorageValue } from "@utils/set-local-storage-value";
+
+export const removeLocalStorageValue = (key: string): void => setLocalStorageValue(key, null);

package/src/utils/set-local-storage-value.ts

@@ -0,0 +1,50 @@
+import { isDefined, Nullable } from "@akb2/types-tools";
+import { deepFreeze } from "@utils/deep-freeze";
+import { getLocalStorageValue } from "@utils/get-local-storage-value";
+import { getOriginalDataStorageKey } from "@utils/get-original-data-storage-key";
+import { SetStateAction } from "react";
+
+export const setLocalStorageValue = <T>(key: string, valueOrCallback: SetStateAction<Nullable<T>>): void => {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const value = typeof valueOrCallback === 'function' ? (valueOrCallback as Function)(getLocalStorageValue<T>(key)) : valueOrCallback;
+
+  if (typeof value === 'function') {
+    throw new Error('Functional updates are not supported in useLocalStorageState setter. Please provide the new value directly.');
+  }
+
+  const currentValue = localStorage.getItem(key) ?? null;
+  const newValue = isDefined(value) ? JSON.stringify({ value }) : null;
+
+  if (isDefined(newValue)) {
+    localStorage.setItem(key, newValue);
+  } else {
+    localStorage.removeItem(key);
+  }
+
+  if (currentValue !== newValue) {
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__)){
+      window.__AKB2_LOCAL_STORAGE__ = { } as typeof window.__AKB2_LOCAL_STORAGE__;
+    }
+
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__.listeners)){
+      window.__AKB2_LOCAL_STORAGE__.listeners = new Map();
+    }
+
+    if(!isDefined(window.__AKB2_LOCAL_STORAGE__.originalData)){
+      window.__AKB2_LOCAL_STORAGE__.originalData = new Map();
+    }
+
+    window.__AKB2_LOCAL_STORAGE__.listeners.get(key)?.forEach((listener) => listener());
+
+    if (isDefined(currentValue)) {
+      window.__AKB2_LOCAL_STORAGE__.originalData.delete(getOriginalDataStorageKey(key, currentValue));
+    }
+
+    if (isDefined(newValue)) {
+      window.__AKB2_LOCAL_STORAGE__.originalData.set(getOriginalDataStorageKey(key, newValue), deepFreeze(JSON.parse(newValue).value));
+    }
+  }
+};