@akb2/react-use-local-storage 1.0.0 → 1.1.1

package/.dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var x=Object.create;var L=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var b=Object.getPrototypeOf,N=Object.prototype.hasOwnProperty;var V=(e,t)=>{for(var o in t)L(e,o,{get:t[o],enumerable:!0})},p=(e,t,o,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let r of D(t))!N.call(e,r)&&r!==o&&L(e,r,{get:()=>t[r],enumerable:!(i=y(t,r))||i.enumerable});return e};var h=(e,t,o)=>(o=e!=null?x(b(e)):{},p(t||!e||!e.__esModule?L(o,"default",{value:e,enumerable:!0}):o,e)),v=e=>p(L({},"__esModule",{value:!0}),e);var z={};V(z,{clearLocalStorage:()=>G,getLocalStorageValue:()=>d,removeLocalStorageValue:()=>C,setLocalStorageValue:()=>f,useLocalStorageState:()=>B});module.exports=v(z);var _=h(require("react"),1);var O=require("@akb2/types-tools");var T=require("@akb2/types-tools"),u=()=>typeof window>"u"?0:(0,T.anyToInt)(window.__AKB2_LOCAL_STORAGE__?.listeners?.size);var s=require("@akb2/types-tools");var a=(e,t)=>`${e}:{${t}}`;var c=e=>{e.storageArea===localStorage&&((0,s.isDefined)(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),(0,s.isDefined)(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),(0,s.isDefined)(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map),(0,s.isDefined)(e.key)?((0,s.isDefined)(e.oldValue)&&e.oldValue!==e.newValue&&window.__AKB2_LOCAL_STORAGE__.originalData.delete(a(e.key,e.oldValue)),window.__AKB2_LOCAL_STORAGE__.listeners.get(e.key)?.forEach(t=>t())):(window.__AKB2_LOCAL_STORAGE__.originalData.clear(),window.__AKB2_LOCAL_STORAGE__.listeners.forEach(t=>t.forEach(o=>o()))))};var m=(e,t)=>{typeof window>"u"||(u()===0&&addEventListener("storage",c),(0,O.isDefined)(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),(0,O.isDefined)(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),window.__AKB2_LOCAL_STORAGE__.listeners.has(e)||window.__AKB2_LOCAL_STORAGE__.listeners.set(e,new Set),window.__AKB2_LOCAL_STORAGE__.listeners.get(e).add(t))};var E=(e,t)=>{typeof window>"u"||window.__AKB2_LOCAL_STORAGE__?.listeners?.has(e)&&(window.__AKB2_LOCAL_STORAGE__.listeners.get(e).delete(t),window.__AKB2_LOCAL_STORAGE__.listeners.get(e)?.size===0&&window.__AKB2_LOCAL_STORAGE__.listeners.delete(e),u()===0&&removeEventListener("storage",c))};var A=require("@akb2/types-tools");var K=require("@akb2/types-tools"),w=e=>(!(0,K.isDefined)(e)||typeof e!="object"||Object.isFrozen(e)||(Object.freeze(e),Object.values(e).forEach(w)),e);function d(e,t=null){let o=t??null;if(typeof window>"u")return o;let i=localStorage.getItem(e);if(!(0,A.isDefined)(i))return o;(0,A.isDefined)(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),(0,A.isDefined)(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map);try{let r=a(e,i),l=window.__AKB2_LOCAL_STORAGE__.originalData.get(r);if((0,A.isDefined)(l))return l;let S=w(JSON.parse(i).value);return(0,A.isDefined)(S)&&window.__AKB2_LOCAL_STORAGE__.originalData.set(r,S),S}catch{return i.length>0?i:o}}var n=require("@akb2/types-tools");var f=(e,t)=>{if(typeof window>"u")return;let o=typeof t=="function"?t(d(e)):t;if(typeof o=="function")throw new Error("Functional updates are not supported in useLocalStorageState setter. Please provide the new value directly.");let i=localStorage.getItem(e)??null,r=(0,n.isDefined)(o)?JSON.stringify({value:o}):null;(0,n.isDefined)(r)?localStorage.setItem(e,r):localStorage.removeItem(e),i!==r&&((0,n.isDefined)(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),(0,n.isDefined)(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),(0,n.isDefined)(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map),window.__AKB2_LOCAL_STORAGE__.listeners.get(e)?.forEach(l=>l()),(0,n.isDefined)(i)&&window.__AKB2_LOCAL_STORAGE__.originalData.delete(a(e,i)),(0,n.isDefined)(r)&&window.__AKB2_LOCAL_STORAGE__.originalData.set(a(e,r),w(JSON.parse(r).value)))};var g=require("react");function B(e,t=null){let o=(0,g.useCallback)(f.bind(null,e),[e]);return[(0,g.useSyncExternalStore)(r=>typeof window>"u"?()=>{}:(m(e,r),()=>E(e,r)),()=>d(e,t),()=>t),o,e]}var R=require("@akb2/types-tools"),G=()=>{if(typeof window>"u")return;let t=Array.from(window.__AKB2_LOCAL_STORAGE__?.listeners?.keys()??[]).reduce((o,i)=>(o.set(i,localStorage.getItem(i)??null),o),new Map);localStorage.clear(),window.__AKB2_LOCAL_STORAGE__?.originalData?.clear(),window.__AKB2_LOCAL_STORAGE__?.listeners?.forEach((o,i)=>{let r=t.get(i);(0,R.isDefined)(r)&&o.forEach(l=>l())})};var C=e=>f(e,null);0&&(module.exports={clearLocalStorage,getLocalStorageValue,removeLocalStorageValue,setLocalStorageValue,useLocalStorageState});

package/.dist/index.d.cts

@@ -0,0 +1,41 @@
+import { Nullable } from '@akb2/types-tools';
+import { Dispatch, SetStateAction } 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.
+ */
+declare function useLocalStorageState<T>(key: string): [Nullable<T>, Dispatch<Nullable<T>>, string];
+declare function useLocalStorageState<T>(key: string, fallback: Exclude<T, null | undefined>): [Exclude<T, null | undefined>, Dispatch<Nullable<T>>, string];
+declare function useLocalStorageState<T>(key: string, fallback: Nullable<T>): [Nullable<T>, Dispatch<Nullable<T>>, string];
+
+declare global {
+    interface Window {
+        __AKB2_LOCAL_STORAGE__: {
+            listeners: Map<string, Set<() => void>>;
+            originalData: Map<string, unknown>;
+        };
+    }
+}
+
+declare const clearLocalStorage: () => void;
+
+/**
+ * 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.
+ */
+declare function getLocalStorageValue<T>(key: string): Nullable<T>;
+declare function getLocalStorageValue<T>(key: string, fallback: Exclude<T, null | undefined>): Exclude<T, null | undefined>;
+declare function getLocalStorageValue<T>(key: string, fallback: Nullable<T>): Nullable<T>;
+
+declare const removeLocalStorageValue: (key: string) => void;
+
+declare const setLocalStorageValue: <T>(key: string, valueOrCallback: SetStateAction<Nullable<T>>) => void;
+
+export { clearLocalStorage, getLocalStorageValue, removeLocalStorageValue, setLocalStorageValue, useLocalStorageState };

package/.dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Nullable } from '@akb2/types-tools';
+import { Dispatch, SetStateAction } 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.
+ */
+declare function useLocalStorageState<T>(key: string): [Nullable<T>, Dispatch<Nullable<T>>, string];
+declare function useLocalStorageState<T>(key: string, fallback: Exclude<T, null | undefined>): [Exclude<T, null | undefined>, Dispatch<Nullable<T>>, string];
+declare function useLocalStorageState<T>(key: string, fallback: Nullable<T>): [Nullable<T>, Dispatch<Nullable<T>>, string];
+
+declare global {
+    interface Window {
+        __AKB2_LOCAL_STORAGE__: {
+            listeners: Map<string, Set<() => void>>;
+            originalData: Map<string, unknown>;
+        };
+    }
+}
+
+declare const clearLocalStorage: () => void;
+
+/**
+ * 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.
+ */
+declare function getLocalStorageValue<T>(key: string): Nullable<T>;
+declare function getLocalStorageValue<T>(key: string, fallback: Exclude<T, null | undefined>): Exclude<T, null | undefined>;
+declare function getLocalStorageValue<T>(key: string, fallback: Nullable<T>): Nullable<T>;
+
+declare const removeLocalStorageValue: (key: string) => void;
+
+declare const setLocalStorageValue: <T>(key: string, valueOrCallback: SetStateAction<Nullable<T>>) => void;
+
+export { clearLocalStorage, getLocalStorageValue, removeLocalStorageValue, setLocalStorageValue, useLocalStorageState };

package/.dist/index.js

@@ -0,0 +1 @@
+import*as _ from"react";import{isDefined as g}from"@akb2/types-tools";import{anyToInt as p}from"@akb2/types-tools";var L=()=>typeof window>"u"?0:p(window.__AKB2_LOCAL_STORAGE__?.listeners?.size);import{isDefined as s}from"@akb2/types-tools";var n=(e,t)=>`${e}:{${t}}`;var u=e=>{e.storageArea===localStorage&&(s(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),s(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),s(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map),s(e.key)?(s(e.oldValue)&&e.oldValue!==e.newValue&&window.__AKB2_LOCAL_STORAGE__.originalData.delete(n(e.key,e.oldValue)),window.__AKB2_LOCAL_STORAGE__.listeners.get(e.key)?.forEach(t=>t())):(window.__AKB2_LOCAL_STORAGE__.originalData.clear(),window.__AKB2_LOCAL_STORAGE__.listeners.forEach(t=>t.forEach(o=>o()))))};var S=(e,t)=>{typeof window>"u"||(L()===0&&addEventListener("storage",u),g(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),g(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),window.__AKB2_LOCAL_STORAGE__.listeners.has(e)||window.__AKB2_LOCAL_STORAGE__.listeners.set(e,new Set),window.__AKB2_LOCAL_STORAGE__.listeners.get(e).add(t))};var O=(e,t)=>{typeof window>"u"||window.__AKB2_LOCAL_STORAGE__?.listeners?.has(e)&&(window.__AKB2_LOCAL_STORAGE__.listeners.get(e).delete(t),window.__AKB2_LOCAL_STORAGE__.listeners.get(e)?.size===0&&window.__AKB2_LOCAL_STORAGE__.listeners.delete(e),L()===0&&removeEventListener("storage",u))};import{isDefined as d}from"@akb2/types-tools";import{isDefined as T}from"@akb2/types-tools";var A=e=>(!T(e)||typeof e!="object"||Object.isFrozen(e)||(Object.freeze(e),Object.values(e).forEach(A)),e);function f(e,t=null){let o=t??null;if(typeof window>"u")return o;let r=localStorage.getItem(e);if(!d(r))return o;d(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),d(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map);try{let i=n(e,r),l=window.__AKB2_LOCAL_STORAGE__.originalData.get(i);if(d(l))return l;let c=A(JSON.parse(r).value);return d(c)&&window.__AKB2_LOCAL_STORAGE__.originalData.set(i,c),c}catch{return r.length>0?r:o}}import{isDefined as a}from"@akb2/types-tools";var w=(e,t)=>{if(typeof window>"u")return;let o=typeof t=="function"?t(f(e)):t;if(typeof o=="function")throw new Error("Functional updates are not supported in useLocalStorageState setter. Please provide the new value directly.");let r=localStorage.getItem(e)??null,i=a(o)?JSON.stringify({value:o}):null;a(i)?localStorage.setItem(e,i):localStorage.removeItem(e),r!==i&&(a(window.__AKB2_LOCAL_STORAGE__)||(window.__AKB2_LOCAL_STORAGE__={}),a(window.__AKB2_LOCAL_STORAGE__.listeners)||(window.__AKB2_LOCAL_STORAGE__.listeners=new Map),a(window.__AKB2_LOCAL_STORAGE__.originalData)||(window.__AKB2_LOCAL_STORAGE__.originalData=new Map),window.__AKB2_LOCAL_STORAGE__.listeners.get(e)?.forEach(l=>l()),a(r)&&window.__AKB2_LOCAL_STORAGE__.originalData.delete(n(e,r)),a(i)&&window.__AKB2_LOCAL_STORAGE__.originalData.set(n(e,i),A(JSON.parse(i).value)))};import{useCallback as m,useSyncExternalStore as E}from"react";function K(e,t=null){let o=m(w.bind(null,e),[e]);return[E(i=>typeof window>"u"?()=>{}:(S(e,i),()=>O(e,i)),()=>f(e,t),()=>t),o,e]}import{isDefined as B}from"@akb2/types-tools";var R=()=>{if(typeof window>"u")return;let t=Array.from(window.__AKB2_LOCAL_STORAGE__?.listeners?.keys()??[]).reduce((o,r)=>(o.set(r,localStorage.getItem(r)??null),o),new Map);localStorage.clear(),window.__AKB2_LOCAL_STORAGE__?.originalData?.clear(),window.__AKB2_LOCAL_STORAGE__?.listeners?.forEach((o,r)=>{let i=t.get(r);B(i)&&o.forEach(l=>l())})};var G=e=>w(e,null);export{R as clearLocalStorage,f as getLocalStorageValue,G as removeLocalStorageValue,w as setLocalStorageValue,K as useLocalStorageState};

package/README.md

@@ -18,54 +18,69 @@ The package provides ESM, CommonJS, and TypeScript declarations.
 import { useLocalStorageState } from "react-use-local-storage";
 
 export const Counter = () => {
-  const [count, setCount] = useLocalStorageState<number>("counter");
+  const [count, setCount] = useLocalStorageState<number>("counter", 0);
 
   return (
-    <button onClick={() => setCount((previous) => (previous ?? 0) + 1)}>
-      Clicks: {count ?? 0}
+    <button onClick={() => setCount(count + 1)}>
+      Clicks: {count}
     </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.
+The optional second argument is a fallback for a missing key. Without a fallback, a missing key returns `null`. The fallback is used for reading and rendering only; it is not written to storage. Removing the key makes the hook return its fallback again.
 
 ## API
 
-### `useLocalStorageState<T>(key)`
+### `useLocalStorageState<T>(key, fallback?)`
 
 ```ts
-const [value, setValue, storageKey] = useLocalStorageState<string>("name");
+const [value, setValue, storageKey] = useLocalStorageState<string>("name", "Guest");
 ```
 
 | 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 |
+| `value` | The stored value, or the fallback for a missing key (`null` by default) |
+| `setValue` | Writes a new value; accepts nullable values for removal |
 | `storageKey` | The key passed to the hook |
 
 ```ts
 setValue("Andrew");
-setValue((previous) => `${previous ?? ""}!`);
+setValue(`${value}!`);
+setValue(null); // Removes the key; this hook returns "Guest" again.
 ```
 
-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.
+The hook's setter is typed as `Dispatch<Nullable<T>>`: pass a value directly. Functional updater callbacks are not part of this public hook signature.
 
-Functions cannot be stored as values: a function argument is treated as an updater, and returning a function from that updater throws an error.
+A non-null fallback selects an overload with a non-null return type. This is a TypeScript declaration, not runtime validation of existing storage data.
 
-### `getLocalStorageValue<T>(key)`
+For object or array fallbacks, reuse a stable reference so that repeated snapshot reads return the same value when the key is missing:
+
+```ts
+const DEFAULT_PREFERENCES = { theme: "light" as const };
+
+// Inside a component:
+const [preferences, setPreferences] = useLocalStorageState<{
+  theme: "light" | "dark";
+}>("preferences", DEFAULT_PREFERENCES);
+```
+
+Avoid passing a newly created object or array as the fallback on every render, especially during server rendering and hydration.
+
+### `getLocalStorageValue<T>(key, fallback?)`
 
 Reads a value without creating a React subscription:
 
 ```ts
 import { getLocalStorageValue } from "react-use-local-storage";
 
-const name = getLocalStorageValue<string>("name");
+const name = getLocalStorageValue<string>("name", "Guest");
+const missing = getLocalStorageValue<string>("missing"); // null if absent
 ```
 
-Returns `undefined` for a missing key. The generic type `T` describes the expected value; it does not validate stored data at runtime.
+Returns the fallback when the key is missing or `window` is unavailable. An omitted, `null`, or `undefined` fallback is normalized to `null` by the getter. The generic type `T` describes the expected value; it does not validate stored data at runtime.
 
-### `setLocalStorageValue<T>(key, valueOrCallback)`
+### `setLocalStorageValue<T>(key, value)`
 
 Writes a value and notifies subscribers to that key in the current window:
 
@@ -73,7 +88,7 @@ Writes a value and notifies subscribers to that key in the current window:
 import { setLocalStorageValue } from "react-use-local-storage";
 
 setLocalStorageValue("name", "Andrew");
-setLocalStorageValue<number>("counter", (previous) => (previous ?? 0) + 1);
+setLocalStorageValue<number>("counter", 1);
 ```
 
 Writing the same serialized content does not notify subscribers again. Passing `null` removes the value.
@@ -127,7 +142,7 @@ export const ThemeButton = () => {
   return (
     <button
       onClick={() =>
-        setPreferences((previous) => ({ ...previous, theme: "dark" }))
+        setPreferences({ ...preferences, theme: "dark" })
       }
     >
       Theme: {preferences?.theme ?? "light"}
@@ -138,6 +153,19 @@ export const ThemeButton = () => {
 
 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.
 
+The fallback does not replace all invalid stored data:
+
+| Stored content | Getter result |
+| --- | --- |
+| Missing key | Fallback, or `null` by default |
+| `{"value":42}` | `42` |
+| `{}` | `undefined`, even with a fallback |
+| `{"value":null}` | `null`, even with a non-null fallback |
+| Nonempty invalid JSON | The original raw string |
+| Empty string | Fallback |
+
+The getter currently returns `parsedData` directly after reading `.value`. Therefore, the non-null fallback overload does not guarantee a non-null runtime result for arbitrary existing data.
+
 ## Synchronization
 
 - In the current window, use the hook's setter or the library utilities to notify subscribers.
@@ -149,9 +177,9 @@ When writing directly from another tab, use the `JSON.stringify({ value: ... })`
 
 ## 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`.
+The hook's server snapshot is its fallback (`null` by default). When `window` is unavailable, the getter returns its fallback, and writes and clearing are no-ops. During hydration, use the same fallback on the server and client. After hydration, React uses the client snapshot from `localStorage`.
 
-Provide a fallback for the initial display, such as `value ?? ""`.
+The fallback does not initialize or overwrite stored data.
 
 ## Limitations
 
@@ -194,4 +222,4 @@ This command builds the package and then publishes it with public access.
 
 ## License
 
-MPL-2.0. Author: akb2.
+MPL-2.0. Author: akb2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akb2/react-use-local-storage",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A state hook with browser's localStorage",
   "exports": {
     ".": {
@@ -9,6 +9,9 @@
       "require": "./.dist/index.cjs"
     }
   },
+  "files": [
+    ".dist"
+  ],
   "keywords": [
     "react",
     "localStorage",

package/.gitignore

@@ -1,144 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
-.env
-.env.*
-!.env.example
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-.dist
-.output
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp directory
-.temp
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# pnpm
-.pnpm-store
-
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-
-# Vite files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
-.vite/

package/.prettierignore

@@ -1,5 +0,0 @@
-**/node_modules/**
-**/.dist/**
-**/dist/**
-**/coverage/**
-pnpm-lock.yaml

package/.prettierrc.json

@@ -1,11 +0,0 @@
-{
-  "semi": true,
-  "singleQuote": false,
-  "jsxSingleQuote": false,
-  "tabWidth": 2,
-  "useTabs": false,
-  "trailingComma": "all",
-  "arrowParens": "always",
-  "printWidth": 100,
-  "endOfLine": "lf"
-}

package/eslint.config.mjs

@@ -1,55 +0,0 @@
-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/pnpm-workspace.yaml

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

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

@@ -1,33 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

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

package/src/types/window.ts

@@ -1,10 +0,0 @@
-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

@@ -1,34 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,8 +0,0 @@
-/**
- * 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

@@ -1,35 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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));
-    }
-  }
-};

package/tests/local-storage-listening.test.ts

@@ -1,28 +0,0 @@
-import { clearLocalStorage, useLocalStorageState } from "@source";
-import { cleanup, renderHook, waitFor } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-beforeEach(() => localStorage.clear());
-
-afterEach(() => {
-  cleanup();
-  clearLocalStorage();
-  vi.useRealTimers();
-});
-
-describe("LocalStorage direct changing", () => {
-  it("No support changes with direct localStorage modification", () => {
-    const { result } = renderHook(() => useLocalStorageState("initial"));
-
-    expect(result.current[0]).toBeUndefined();
-
-    localStorage.setItem(
-      "initial",
-      JSON.stringify({ value: "new value with direct modification" }),
-    );
-
-    return waitFor(() => expect(result.current[0]).toBe(undefined), {
-      timeout: 2000,
-    });
-  });
-});

package/tests/simple-change.test.ts

@@ -1,40 +0,0 @@
-import { clearLocalStorage, useLocalStorageState } from "@source";
-import { act, cleanup, renderHook } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-beforeEach(() => localStorage.clear());
-
-afterEach(() => {
-  cleanup();
-  clearLocalStorage();
-  vi.useRealTimers();
-});
-
-describe("A simple value changing", () => {
-  it("No changing a value", () => {
-    const { result } = renderHook(() => useLocalStorageState("initial"));
-
-    expect(result.current[0]).toBeUndefined();
-  });
-
-  it("Changing a value", () => {
-    const { result } = renderHook(() => useLocalStorageState("initial"));
-
-    expect(result.current[0]).toBeUndefined();
-    act(() => result.current[1]("new value"));
-    expect(result.current[0]).toBe("new value");
-  });
-
-  it("Change a value with timeout", () => {
-    vi.useFakeTimers();
-
-    const { result } = renderHook(() => useLocalStorageState("initial"));
-
-    expect(result.current[0]).toBeUndefined();
-    setTimeout(() => result.current[1]("new value with timeout"), 100);
-    act(() => vi.advanceTimersByTime(99));
-    expect(result.current[0]).toBeUndefined();
-    act(() => vi.advanceTimersByTime(1));
-    expect(result.current[0]).toBe("new value with timeout");
-  });
-});

package/tests/tsconfig.json

@@ -1,3 +0,0 @@
-{
-  "extends": "../tsconfig.test.json"
-}

package/tsconfig.json

@@ -1,33 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "declaration": true,
-    "strict": true,
-    "moduleResolution": "Bundler",
-    "skipLibCheck": true,
-    "outDir": ".dist",
-    "rootDir": ".",
-    "esModuleInterop": true,
-    "jsx": "react-jsx",
-    "jsxImportSource": "preact",
-    "types": [
-      "react",
-      "react-dom"
-    ],
-    "paths": {
-      "@hooks/*": [
-        "./src/hooks/*"
-      ],
-      "@utils/*": [
-        "./src/utils/*"
-      ],
-      "@types/*": [
-        "./src/types/*"
-      ]
-    }
-  },
-  "include": [
-    "src"
-  ]
-}

package/tsconfig.test.json

@@ -1,31 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "declaration": false,
-    "rootDir": ".",
-    "lib": [
-      "ES2020",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": [
-      "node",
-      "vitest/globals"
-    ],
-    "paths": {
-      "@source": [
-        "./src/index.ts"
-      ]
-    }
-  },
-  "include": [
-    "tests/**/*.ts",
-    "tests/**/*.tsx",
-    "vitest.config.ts"
-  ],
-  "exclude": [
-    "node_modules",
-    ".dist"
-  ]
-}

package/vitest.config.ts

@@ -1,19 +0,0 @@
-import { fileURLToPath } from "node:url";
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "jsdom",
-    environmentOptions: {
-      jsdom: {
-        url: "http://localhost/",
-      },
-    },
-    alias: {
-      "@source": fileURLToPath(new URL("./src/index.ts", import.meta.url)),
-      "@utils": fileURLToPath(new URL("./src/utils", import.meta.url)),
-      "@types": fileURLToPath(new URL("./src/types", import.meta.url)),
-      "@hooks": fileURLToPath(new URL("./src/hooks", import.meta.url)),
-    },
-  },
-});