use-json-localstorage 0.4.0 → 1.3.0

package/README.md

@@ -0,0 +1,180 @@
+# use-json-localstorage
+
+A tiny, **React 18+ safe** localStorage utility built on top of `useSyncExternalStore`.
+
+> Most `useLocalStorage` hooks rely on `useEffect + useState`, which can be unsafe in concurrent rendering.
+> This library follows the **official React pattern** for subscribing to external stores.
+
+---
+
+## Why
+
+React 18 introduced **concurrent rendering**. In this environment, the common pattern below is no longer safe:
+
+```ts
+useEffect(() => {
+  store.subscribe(setState);
+}, []);
+```
+
+This can lead to:
+
+* tearing (inconsistent state during render)
+* unexpected double renders in Strict Mode
+* subtle bugs that are hard to reproduce
+
+React provides a solution for this exact problem:
+
+```ts
+useSyncExternalStore
+```
+
+`use-json-localstorage` is a small abstraction that applies this API to `localStorage`.
+
+---
+
+## Features
+
+* ✅ React 18+ safe (`useSyncExternalStore`)
+* ✅ JSON-based persistence (via `superjson`)
+* ✅ Subscribable localStorage updates
+* ✅ Type-safe API
+* ✅ Tiny & opinionated
+
+---
+
+## Non-goals
+
+This library **does NOT aim to be**:
+
+* a global state manager (Redux, Zustand, etc.)
+* an ORM or database abstraction
+* a complex query engine
+* a replacement for server-side persistence
+
+It is intentionally small.
+
+---
+
+## Install
+
+```bash
+npm install use-json-localstorage
+```
+
+React 18 or higher is required.
+
+---
+
+## Basic Usage
+
+```ts
+import { useLocalStorageValue } from 'use-json-localstorage';
+
+function Counter() {
+  const count = useLocalStorageValue('count', 0);
+
+  return <div>{count}</div>;
+}
+```
+
+* `count` is read from `localStorage`
+* updates are subscribed via `useSyncExternalStore`
+* React always receives a consistent snapshot
+
+---
+
+## Writing Values
+
+```ts
+import { getRuntimeLocalStorage } from 'use-json-localstorage';
+
+getRuntimeLocalStorage().set('count', 1);
+```
+
+All subscribers of the same key will be notified.
+
+---
+
+## Supported Data Types
+
+Serialization is handled by `superjson`, which means the following are supported:
+
+* `Object`
+* `Array`
+* `Date`
+* `Map`
+* `Set`
+* `BigInt`
+
+---
+
+## How It Works
+
+At a high level:
+
+1. `localStorage` is wrapped as an **evented external store**
+2. React subscribes via `useSyncExternalStore`
+3. Updates trigger a re-render using a fresh snapshot
+
+```txt
+localStorage
+   ↓
+event emitter
+   ↓
+useSyncExternalStore
+   ↓
+React render
+```
+
+This follows the same pattern used internally by modern state libraries.
+
+---
+
+## Example: Mutation-style Update
+
+```ts
+getRuntimeLocalStorage().set('user', {
+  id: '1',
+  name: 'Dohyeon',
+});
+```
+
+You can build schema-based mutation helpers on top of this primitive.
+
+---
+
+## SSR
+
+This library is **client-only**.
+
+* No SSR persistence
+* No server synchronization
+
+---
+
+## License
+
+MIT
+
+---
+
+## Motivation
+
+This project was created to explore:
+
+* React 18 concurrency-safe patterns
+* External store design
+* A minimal, explainable alternative to ad-hoc `useLocalStorage` hooks
+
+If you are building UI infrastructure or headless utilities, this pattern may be useful.
+
+---
+
+## Credits
+
+Inspired by the React 18 RFC and the design of modern state libraries.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-json-localstorage",
-  "version": "0.4.0",
+  "version": "1.3.0",
   "description": "JSON local storage for React",
   "repository": {
     "type": "git",
@@ -46,4 +46,4 @@
   "dependencies": {
     "superjson": "^2.2.6"
   }
-}
+}