@@ -28,7 +24,7 @@ export function SettingsForm() { Theme { settingsStore.theme = e.target.value as 'light' | 'dark' | 'system'; }} @@ -40,12 +36,14 @@ export function SettingsForm() { - Font Size: {snap.fontSize}px + + Font Size: {store.fontSize}px + { settingsStore.fontSize = Number(e.target.value); }} @@ -56,7 +54,7 @@ export function SettingsForm() { { settingsStore.compactMode = !settingsStore.compactMode; }} @@ -68,7 +66,7 @@ export function SettingsForm() { { settingsStore.notifications = !settingsStore.notifications; }} @@ -82,7 +80,7 @@ export function SettingsForm() { { settingsStore.defaultServings = Number(e.target.value) || 1; }} @@ -93,7 +91,7 @@ export function SettingsForm() { Measurement Unit { settingsStore.measurementUnit = e.target.value as | 'metric' diff --git a/examples/nextjs/src/components/shared/StoreHydrator.tsx b/examples/nextjs/src/components/shared/StoreHydrator.tsx new file mode 100644 index 0000000..fa9fd79 --- /dev/null +++ b/examples/nextjs/src/components/shared/StoreHydrator.tsx @@ -0,0 +1,23 @@ +'use client'; + +import {type ReactNode, useEffect, useState} from 'react'; +import {settingsPersist} from '@/stores/settings-store'; +import {shoppingPersist} from '@/stores/shopping-store'; + +const persists = [settingsPersist, shoppingPersist]; + +export function StoreHydrator({children}: {children: ReactNode}) { + const [hydrated, setHydrated] = useState(false); + + useEffect(() => { + Promise.all(persists.map((p) => p.rehydrate())).then(() => + setHydrated(true), + ); + }, []); + + if (!hydrated) { + return null; + } + + return <>{children}; +} diff --git a/examples/nextjs/src/stores/planner-store.ts b/examples/nextjs/src/stores/planner-store.ts index 520fe30..0efb490 100644 --- a/examples/nextjs/src/stores/planner-store.ts +++ b/examples/nextjs/src/stores/planner-store.ts @@ -92,7 +92,6 @@ export const plannerPersist = persist(plannerStore, { return state; }, merge: 'shallow', - skipHydration: true, syncTabs: true, expireIn: 7 * 24 * 60 * 60 * 1000, clearOnExpire: true, diff --git a/examples/nextjs/src/stores/settings-store.ts b/examples/nextjs/src/stores/settings-store.ts index 7b20b9b..49c25bb 100644 --- a/examples/nextjs/src/stores/settings-store.ts +++ b/examples/nextjs/src/stores/settings-store.ts @@ -1,14 +1,16 @@ import {createClassyStore} from '@codebelt/classy-store'; import {devtools, persist} from '@codebelt/classy-store/utils'; -export const settingsStore = createClassyStore({ - theme: 'system' as 'light' | 'dark' | 'system', - fontSize: 16, - compactMode: false, - notifications: true, - defaultServings: 4, - measurementUnit: 'metric' as 'metric' | 'imperial', -}); +class SettingsStore { + theme = 'system' as 'light' | 'dark' | 'system'; + fontSize = 16; + compactMode = false; + notifications = true; + defaultServings = 4; + measurementUnit = 'metric' as 'metric' | 'imperial'; +} + +export const settingsStore = createClassyStore(new SettingsStore()); export const settingsPersist = persist(settingsStore, { name: 'classy-kitchen-settings', diff --git a/website/docs/PERSIST_TUTORIAL.md b/website/docs/PERSIST_TUTORIAL.md index d916efe..cc6b51c 100644 --- a/website/docs/PERSIST_TUTORIAL.md +++ b/website/docs/PERSIST_TUTORIAL.md @@ -1,17 +1,18 @@ -# Persist Tutorial +# Classy Store Persist Utility -`persist()` saves your store's state to storage and restores it on page load. It's a standalone utility function that works with any `createClassyStore()` instance -- no plugins, no middleware, no configuration files. Import it from `@codebelt/classy-store/utils`, call it once, and your store survives page refreshes. +`persist()` saves your store's state to storage and restores it on page load. It's a standalone utility function that works with any `createClassyStore()` instance. ## Getting Started ### 1. Create a store ```ts +// todoStore.ts import {createClassyStore} from '@codebelt/classy-store'; class TodoStore { - todos: { text: string; done: boolean }[] = []; filter: 'all' | 'active' | 'done' = 'all'; + todos: {text: string; done: boolean}[] = []; get remaining() { return this.todos.filter((todo) => !todo.done).length; @@ -22,7 +23,7 @@ class TodoStore { } toggle(index: number) { - this.todos[index]!.done = !this.todos[index]!.done; + this.todos[index].done = !this.todos[index]!.done; } } @@ -32,33 +33,35 @@ export const todoStore = createClassyStore(new TodoStore()); ### 2. Persist it ```ts +// todoStore.ts +import {createClassyStore} from '@codebelt/classy-store'; import {persist} from '@codebelt/classy-store/utils'; +// ... (Include TodoStore setup from Step 1) + +// Saves all store properties to localStorage const handle = persist(todoStore, { name: 'todo-store', }); ``` -That's it. On every mutation, `todos` and `filter` are saved to `localStorage`. On next page load, they're restored automatically. The getter `remaining` and the methods `addTodo`/`toggle` are **not** persisted -- getters are derived values that recompute from the persisted data, and methods are functions that don't belong in storage. - -### 3. Wait for hydration - -If you need to know when the stored data has been applied to the store: +**What gets stored in storage:** -```ts -// Async -- await the promise -await handle.hydrated; -console.log('Restored:', todoStore.todos); - -// Sync check -if (handle.isHydrated) { - // safe to read persisted state +```json +// In localStorage the key will be `todo-store` and the value will be: +{ + "version": 0, + "state": { + "todos": [], + "filter": "all" + }, + "expiresAt": 300000 // Only present if you set the expireIn option (5 minutes) } ``` -For `localStorage` (synchronous), hydration resolves almost immediately. For async storage adapters like `AsyncStorage`, the promise resolves after the async read completes. +On every mutation, `todos` and `filter` are saved to `localStorage`. On next page load, they're restored automatically. The getter `remaining` and the methods `addTodo`/`toggle` are **not** persisted -- getters are derived values that recompute from the persisted data, and methods are functions that don't belong in storage. -## Choosing What to Persist +### Choosing What to Persist By default, `persist()` saves all own data properties of the store -- everything that isn't a getter or a method. You can narrow this with the `properties` option: @@ -73,67 +76,55 @@ Now `filter` resets to its class default (`'all'`) on every page load, while `to ### Why getters are excluded -Class getters like `get remaining()` are derived values. They compute their result from the persisted data properties (`todos`) every time they're accessed. Persisting a getter result would be redundant and risks restoring a stale value that contradicts the underlying data. Persist only the inputs; the outputs take care of themselves. - -## Per-Property Transforms +Class getters like `get remaining()` are derived values. They compute their results from the data property (`todos`) every time they're accessed. Persisting a getter result would be redundant and risks restoring a stale value that contradicts the underlying data. -Some values aren't JSON-safe. `Date` objects become strings, `ReactiveMap` instances lose their structure, and custom classes vanish entirely after `JSON.stringify` + `JSON.parse`. Transforms handle the round-trip. +### Configuration and Handle Overview -### Dates +Here is a quick overview of every configuration option and handle method. You won't need most of them day-to-day, but they're available when you do. ```ts -class SessionStore { - token = ''; - expiresAt = new Date(); - - get isExpired() { - return this.expiresAt < new Date(); - } -} - -const sessionStore = createClassyStore(new SessionStore()); +import {persist} from '@codebelt/classy-store/utils'; -persist(sessionStore, { - name: 'session', - properties: [ - 'token', // plain key -- string, no transform needed - { - key: 'expiresAt', - serialize: (date) => date.toISOString(), // Date → string - deserialize: (stored) => new Date(stored as string), // string → Date - }, - ], +const handle = persist(todoStore, { + name: 'TodoStore', // Unique storage key (required) + properties: [], // Keys or transform descriptors to persist (default: all own data properties) + storage: localStorage, // Storage adapter with getItem/setItem/removeItem (default: localStorage) + debounce: 500, // Coalesce rapid mutations into one write, in ms (default: 0) + version: 0, // Schema version number; triggers migrate when mismatched (default: 0) + migrate: (state, v) => {}, // Called when stored version ≠ current; must return state in current shape + merge: 'shallow', // How to merge persisted state on hydration: 'shallow' | 'replace' | custom fn + skipHydration: true, // Don't hydrate on init; call handle.rehydrate() manually (default: false) + syncTabs: true, // Re-hydrate when another tab writes to the same key (localStorage only) + expireIn: 1000, // TTL in ms; expired data is skipped on hydration. Resets on every write + clearOnExpire: false, // Auto-remove storage key when expired data is found (default: false) }); -``` - -**In storage:** -```json -{ - "version": 0, - "state": { - "token": "eyJhbGciOiJIUz...", - "expiresAt": "2026-02-14T00:00:00.000Z" - } -} +handle.isHydrated; // Whether hydration from storage has completed +handle.isExpired; // True if last hydration found expired data (requires expireIn) +await handle.hydrated; // Promise that resolves when initial hydration is complete +await handle.save(); // Manually write to storage (bypasses debounce) +await handle.clear(); // Remove this store's persisted data from storage +await handle.rehydrate(); // Manually re-hydrate the store from storage +handle.unsubscribe(); // Stop persisting: unsubscribe + cancel debounce + remove storage listener ``` -On restore, `deserialize` converts the ISO string back into a `Date` object before assigning it to `sessionStore.expiresAt`. +--- -### ReactiveMap +## Configuration Properties -`reactiveMap()` instances are backed by internal arrays that aren't directly JSON-serializable: +### `properties` (Per-Property Transforms) -```ts -import {createClassyStore} from '@codebelt/classy-store'; -import {reactiveMap} from '@codebelt/classy-store/collections'; -import {persist} from '@codebelt/classy-store/utils'; +Some values aren't JSON-safe. `Date` objects become strings, and custom classes vanish entirely after `JSON.stringify` + `JSON.parse`. Transforms handle the round-trip through the `properties` option. +```ts class UserStore { - users = reactiveMap(); + name = ''; + birthdate = new Date(); - addUser(id: string, name: string, role: string) { - this.users.set(id, {name, role}); + get isAdult() { + const cutoff = new Date(); + cutoff.setFullYear(cutoff.getFullYear() - 18); + return this.birthdate <= cutoff; } } @@ -142,10 +133,11 @@ const userStore = createClassyStore(new UserStore()); persist(userStore, { name: 'user-store', properties: [ + 'name', // plain key -- string, no transform needed { - key: 'users', - serialize: (users) => [...users.entries()], // ReactiveMap → array of tuples - deserialize: (stored) => reactiveMap(stored as [string, { name: string; role: string }][]), + key: 'birthdate', + serialize: (date) => date.toISOString(), // Date → string + deserialize: (stored) => new Date(stored as string), // string → Date }, ], }); @@ -157,142 +149,50 @@ persist(userStore, { { "version": 0, "state": { - "users": [ - ["u1", { "name": "Alice", "role": "admin" }], - ["u2", { "name": "Bob", "role": "viewer" }] - ] + "name": "Robert", + "birthdate": "2026-02-14T00:00:00.000Z" } } ``` -The same pattern works for `reactiveSet()` -- serialize to an array, deserialize back with `reactiveSet()`. - -## Debouncing Writes - -For stores that mutate frequently (form inputs, drag positions, real-time data), debouncing prevents excessive writes: - -```ts -persist(formStore, { - name: 'form-draft', - debounce: 500, // Write at most once every 500ms -}); - -// Rapid mutations: -formStore.name = 'J'; -formStore.name = 'Jo'; -formStore.name = 'John'; -// One write to storage, 500ms after the last mutation. -``` - -### Manual save - -When you need to save immediately (e.g., before the user navigates away): +On restore, `deserialize` converts the ISO string back into a `Date` object before assigning it to `userStore.birthdate`. -```ts -const handle = persist(formStore, { - name: 'form-draft', - debounce: 1000, -}); +*(If you need to persist `Map` or `Set` objects, see the [Reactive Collections Tutorial](./REACTIVE_COLLECTIONS_TUTORIAL.md).)* -// Force save before page unload -window.addEventListener('beforeunload', () => { - handle.save(); -}); -``` +### `storage` -`save()` cancels the pending debounce timer and writes the current state immediately. +`persist()` handles different storage adapters transparently. The default is `localStorage`. Any object with `getItem`, `setItem`, and `removeItem` (sync or async) works. -## Version Migration +**sessionStorage (Tab-Scoped)** -When the store's shape changes between releases, versioning and migration prevent data loss: +Use `sessionStorage` for state that should reset when the tab closes: ```ts -persist(todoStore, { - name: 'todo-store', - version: 2, - migrate: (state, oldVersion) => { - if (oldVersion === 0) { - // v0 stored todos as `items` - return {...state, todos: state.items, items: undefined}; - } - if (oldVersion === 1) { - // v1 todos were plain strings, v2 todos are objects - return { - ...state, - todos: (state.todos as string[]).map((text) => ({text, done: false})), - }; - } - return state; - }, +persist(uiStore, { + name: 'ui-state', + storage: sessionStorage, + properties: ['sidebarOpen', 'activeTab'], + // syncTabs defaults to false for sessionStorage }); ``` -**How it works:** -1. Data is stored with a version number: `{ "version": 2, "state": { ... } }`. -2. On hydration, if the stored version doesn't match the current `version`, `migrate` is called with the raw state and the old version number. -3. `migrate` returns the state transformed into the current shape. -4. The transformed state is then applied to the store normally. - -If no `migrate` function is provided and versions mismatch, the old data is applied as-is -- which may silently produce incorrect state. Always pair `version` with `migrate`. - -## Merge Strategies +**Async Storage (React Native)** -When you add new properties to a store, old persisted data won't include them. The merge strategy controls how persisted state combines with the store's current state: - -### Shallow (default) - -Persisted values overwrite the store's current values one key at a time. Properties not in storage keep their class defaults. +`AsyncStorage` from React Native works out of the box: ```ts -class SettingsStore { - theme: 'light' | 'dark' = 'light'; - fontSize = 14; - sidebar = true; // NEW -- not in old persisted data - language = 'en'; // NEW -- not in old persisted data -} +import AsyncStorage from '@react-native-async-storage/async-storage'; -persist(createClassyStore(new SettingsStore()), { - name: 'settings', - // merge: 'shallow', // default +const handle = persist(todoStore, { + name: 'todo-store', + storage: AsyncStorage, + syncTabs: false, // no window.storage in React Native }); -// Old storage has: { theme: 'dark', fontSize: 16 } -// After hydration: -// theme = 'dark' (from storage) -// fontSize = 16 (from storage) -// sidebar = true (class default -- not in storage) -// language = 'en' (class default -- not in storage) -``` - -### Replace - -Same behavior as `'shallow'` for flat stores. The distinction matters for nested objects -- `'replace'` replaces the entire nested object rather than merging keys into it. - -### Custom merge function - -For full control, pass a function that receives `(persistedState, currentState)` and returns the merged state: - -```ts -persist(settingsStore, { - name: 'settings', - merge: (persisted, current) => { - const merged = {...current}; - for (const key of Object.keys(persisted)) { - const persistedValue = persisted[key]; - const currentValue = current[key]; - // Deep merge one level for nested objects - if (persistedValue && currentValue && typeof persistedValue === 'object' && typeof currentValue === 'object') { - merged[key] = {...currentValue, ...persistedValue}; - } else { - merged[key] = persistedValue; - } - } - return merged; - }, -}); +await handle.hydrated; ``` -## Cross-Tab Synchronization +### `syncTabs` (Cross-Tab Synchronization) When using `localStorage`, state syncs automatically across browser tabs. If a user logs out in Tab A, Tab B picks up the change immediately: @@ -309,10 +209,9 @@ authStore.user = null; // Tab B: automatically receives the update // --> authStore.token and authStore.user become null -// --> React components re-render via normal reactivity ``` -This works via the browser's `window.storage` event, which fires in all **other** same-origin tabs (not the one that wrote). The persist utility listens for changes to its storage key and re-hydrates when it detects a write from another tab. +This works via the browser's `window.storage` event, which fires in all **other** same-origin tabs. The persist utility listens for changes to its storage key and re-hydrates when it detects a write from another tab. Disable it when you don't want cross-tab sync: @@ -325,7 +224,7 @@ persist(uiStore, { Cross-tab sync only works with `localStorage`. It does not fire for `sessionStorage`, `AsyncStorage`, or custom adapters. -## Expiration / TTL +### `expireIn` & `clearOnExpire` (Expiration / TTL) Use `expireIn` to set a time-to-live (in milliseconds) on persisted data. After the TTL elapses, stored data is skipped during hydration and the store keeps its class defaults. @@ -338,7 +237,7 @@ persist(sessionStore, { **The TTL resets on every write.** As long as mutations keep happening (an active user session), the data stays fresh. The countdown only matters when the store is hydrated from storage after a period of inactivity (e.g., a page reload). -### Checking expiration +**Checking expiration** The handle exposes an `isExpired` flag that becomes `true` when hydration encounters expired data: @@ -352,14 +251,9 @@ await handle.hydrated; if (handle.isExpired) { // Stored session expired — redirect to login - router.push('/login'); } ``` -`isExpired` is re-evaluated on every `rehydrate()` call, so you can poll or re-check after cross-tab sync events. - -### Auto-clearing expired data - By default, expired data is skipped but left in storage. Set `clearOnExpire: true` to automatically remove the key: ```ts @@ -370,19 +264,15 @@ persist(sessionStore, { }); ``` -### Cross-tab sync and expiration - -Expired envelopes received from other tabs via `window.storage` events are also rejected. The same expiry check runs on every hydration path — init, `rehydrate()`, and cross-tab sync. - -## SSR / Next.js Support +### `skipHydration` (SSR / Next.js Support) `persist()` is SSR-safe out of the box. When `localStorage` is unavailable (server-side rendering, restricted environments), it returns a **dormant handle** instead of throwing. The store keeps its class defaults on the server, and you activate persistence on the client via `rehydrate()`. -This means you can call `persist()` at module scope — no `typeof window` guards needed: +This means you can call `persist()` at module scope -- no `typeof window` guards needed: ```ts -// store.ts — runs on both server and client -const handle = persist(todoStore, { +// store.ts -- runs on both server and client +export const handle = persist(todoStore, { name: 'todo-store', skipHydration: true, }); @@ -392,6 +282,7 @@ Then hydrate manually in a `useEffect` (which only runs on the client): ```tsx import {useEffect} from 'react'; +import {handle} from './store'; function App() { useEffect(() => { @@ -402,81 +293,201 @@ function App() { } ``` -When `rehydrate()` is called on a dormant handle, it re-checks for storage availability. If `localStorage` is now accessible (client-side), it bootstraps the full persist lifecycle — hydration, mutation subscription, and cross-tab sync — as if `persist()` had been called with storage available from the start. +#### The hydration mismatch problem + +In SSR frameworks like Next.js, the server renders HTML using the store's class defaults (e.g., `theme = 'light'`). When the client hydrates, if `persist()` has already restored a different value from `localStorage` (e.g., `theme = 'dark'`), React sees a mismatch between the server-rendered HTML and the client state. This causes a **hydration error**. + +Setting `skipHydration: true` prevents `persist()` from reading `localStorage` until you explicitly call `rehydrate()` — letting you control *when* the stored state is applied and avoid the mismatch. -You can also wait for hydration before rendering content: +#### `StoreHydrator` component pattern + +When you have multiple persisted stores, calling `rehydrate()` in individual components is repetitive. A better pattern is a single `StoreHydrator` component that gates rendering until all stores are hydrated: ```tsx -function App() { - const [ready, setReady] = useState(false); +// StoreHydrator.tsx +'use client'; + +import {type ReactNode, useEffect, useState} from 'react'; +import {settingsPersist} from './stores/settings-store'; +import {todoPersist} from './stores/todo-store'; + +// Collect all persist handles that use skipHydration: true +const persists = [settingsPersist, todoPersist]; + +export function StoreHydrator({children}: {children: ReactNode}) { + const [hydrated, setHydrated] = useState(false); useEffect(() => { - handle.rehydrate().then(() => setReady(true)); + Promise.all(persists.map((p) => p.rehydrate())).then(() => + setHydrated(true), + ); }, []); - if (!ready) return ; - return ; + if (!hydrated) { + return null; // or a loading spinner + } + + return <>{children}; } ``` -### Dormant handle behavior +Wrap your app layout with `StoreHydrator` so nothing renders until `localStorage` values have been applied: -When no storage is available, the dormant handle: +```tsx +// layout.tsx (Next.js App Router) +import {StoreHydrator} from '@/components/StoreHydrator'; + +export default function RootLayout({children}: {children: React.ReactNode}) { + return ( + + + + + {children} + + + + ); +} +``` + +**How it works:** -- `isHydrated` — `true` (resolved immediately with defaults, no storage to read from) -- `isExpired` — `false` -- `hydrated` — resolves immediately -- `save()`, `clear()`, `unsubscribe()` — safe to call (no-ops) -- `rehydrate()` — re-checks for storage; activates full persistence if found +1. The server renders the page using each store's class defaults — no `localStorage` access. +2. On the client, `StoreHydrator` mounts and calls `rehydrate()` on every persist handle. +3. Until all handles resolve, `StoreHydrator` renders `null` (or a loading indicator), preventing any child component from reading stale default values. +4. Once hydration completes, children render with the correct `localStorage`-restored state — no mismatch. -## Async Storage (React Native) +### `debounce` (Debouncing Writes) -`persist()` handles async storage adapters transparently. `AsyncStorage` from React Native works out of the box: +For stores that mutate frequently (form inputs, drag positions, real-time data), debouncing prevents excessive writes: ```ts -import AsyncStorage from '@react-native-async-storage/async-storage'; +persist(formStore, { + name: 'form-draft', + debounce: 500, // Write at most once every 500ms +}); + +// Rapid mutations: +formStore.name = 'J'; +formStore.name = 'Jo'; +formStore.name = 'John'; +// One write to storage, 500ms after the last mutation. +``` +### `version`, `migrate`, & `merge` (Version Migration and Strategies) + +When the store's shape changes between releases, versioning and migration prevent data loss: + +```ts persist(todoStore, { name: 'todo-store', - storage: AsyncStorage, - syncTabs: false, // no window.storage in React Native + version: 2, + migrate: (state, oldVersion) => { + if (oldVersion === 0) { + // v0 stored todos as `items` + return {...state, todos: state.items, items: undefined}; + } + if (oldVersion === 1) { + // v1 todos were plain strings, v2 todos are objects + return { + ...state, + todos: (state.todos as string[]).map((text) => ({text, done: false})), + }; + } + return state; + }, }); - -await handle.hydrated; ``` -Any object with `getItem`, `setItem`, and `removeItem` (sync or async) works as a storage adapter. +**Merge Strategies** -## sessionStorage (Tab-Scoped) +When you add new properties to a store, old persisted data won't include them. The `merge` strategy controls how persisted state combines with the store's current state. -Use `sessionStorage` for state that should reset when the tab closes: +Imagine your store adds a new `tags` property, but old persisted data only has `todos` and `filter`: ```ts -persist(uiStore, { - name: 'ui-state', - storage: sessionStorage, - properties: ['sidebarOpen', 'activeTab'], - // syncTabs defaults to false for sessionStorage +// Current store class (v2 — added `tags`) +class TodoStore { + filter: 'all' | 'active' | 'done' = 'all'; + todos: {text: string; done: boolean}[] = []; + tags: string[] = ['work', 'personal']; // new property with defaults +} + +// Old persisted data in storage (no `tags` key): +// { "version": 1, "state": { "filter": "done", "todos": [{"text": "Buy milk", "done": false}] } } +``` + +**`'shallow'`** (default) — persisted values overwrite current values one key at a time. Properties not in storage keep their default value: + +```ts +persist(todoStore, { + name: 'todo-store', + merge: 'shallow', }); + +// Result after hydration: +// filter → "done" (from storage) +// todos → [{text: "Buy milk", done: false}] (from storage) +// tags → ["work", "personal"] (kept class default) ``` -## Cleanup +**`'replace'`** — only persisted keys are assigned. New properties not in storage are dropped. For nested objects, the entire object is replaced rather than merged: -### Stop persisting +```ts +persist(todoStore, { + name: 'todo-store', + merge: 'replace', +}); + +// Result after hydration: +// filter → "done" (from storage) +// todos → [{text: "Buy milk", done: false}] (from storage) +// tags → undefined (not in storage, dropped) +``` + +**Custom function** — for full control, pass a function that receives `(persisted, current)` and returns the merged state: ```ts -const handle = persist(todoStore, {name: 'todo-store'}); +persist(todoStore, { + name: 'todo-store', + merge: (persisted, current) => { + return { + ...current, // start with class defaults + ...persisted, // overwrite with stored values + tags: [ // custom: combine stored + default tags + ...new Set([ + ...(persisted.tags as string[] ?? []), + ...(current.tags as string[] ?? []), + ]), + ], + }; + }, +}); +``` -// Later: stop all persistence (e.g., on logout) -handle.unsubscribe(); +--- -// Mutations after this point are NOT written to storage. -// Cross-tab sync listener is also removed. -// Pending debounce timer is cancelled. -todoStore.addTodo('This is not persisted'); +## The Handle + +### `isHydrated` & `hydrated` + +If you need to know when the stored data has been applied to the store: + +```ts +// Async -- await the promise +await handle.hydrated; +console.log('Restored:', todoStore.todos); + +// Sync check +if (handle.isHydrated) { + // safe to read persisted state +} ``` -### Clear stored data +For `localStorage` (synchronous), hydration resolves almost immediately. For async storage adapters like `AsyncStorage`, the promise resolves after the async read completes. + +### `clear()` (Clear stored data) ```ts // Remove the stored data without affecting in-memory state @@ -486,22 +497,40 @@ await handle.clear(); // Next page load starts with class defaults (nothing in storage). ``` -### Full reset +### `save()` (Manual save) + +When you need to save immediately (e.g., before the user navigates away): ```ts -async function resetToDefaults() { - handle.unsubscribe(); // Stop persisting - await handle.clear(); // Remove from storage +const handle = persist(formStore, { + name: 'form-draft', + debounce: 1000, +}); - // Reset in-memory state manually: - todoStore.todos = []; - todoStore.filter = 'all'; +// Force save before page unload +window.addEventListener('beforeunload', () => { + handle.save(); +}); +``` - // Optionally re-enable persistence: - const newHandle = persist(todoStore, {name: 'todo-store'}); -} +`save()` cancels the pending debounce timer and writes the current state immediately. + +### `unsubscribe()` (Stop persisting) + +```ts +const handle = persist(todoStore, {name: 'todo-store'}); + +// Later: stop all persistence (e.g., on logout) +handle.unsubscribe(); + +// Mutations after this point are NOT written to storage. +// Cross-tab sync listener is also removed. +// Pending debounce timer is cancelled. +todoStore.addTodo('This is not persisted'); ``` +--- + ## Multiple Persistence Targets Call `persist()` multiple times with different options to persist different parts of a store to different locations: @@ -529,26 +558,16 @@ Here's a complete example combining several features: ```ts import {createClassyStore} from '@codebelt/classy-store'; -import {reactiveMap} from '@codebelt/classy-store/collections'; import {persist} from '@codebelt/classy-store/utils'; class AppStore { theme: 'light' | 'dark' = 'light'; language = 'en'; lastLogin = new Date(0); - bookmarks = reactiveMap(); - - get bookmarkCount() { - return this.bookmarks.size; - } setTheme(theme: 'light' | 'dark') { this.theme = theme; } - - addBookmark(id: string, title: string, url: string) { - this.bookmarks.set(id, {title, url}); - } } const appStore = createClassyStore(new AppStore()); @@ -566,12 +585,6 @@ const handle = persist(appStore, { serialize: (date) => date.toISOString(), deserialize: (stored) => new Date(stored as string), }, - { - key: 'bookmarks', - serialize: (map) => [...map.entries()], - deserialize: (stored) => - reactiveMap(stored as [string, { title: string; url: string }][]), - }, ], migrate: (state, oldVersion) => { @@ -585,29 +598,30 @@ const handle = persist(appStore, { // Wait for hydration, then start the app await handle.hydrated; -console.log(`Welcome back! Theme: ${appStore.theme}, Bookmarks: ${appStore.bookmarkCount}`); +console.log(`Welcome back! Theme: ${appStore.theme}`); ``` ## Quick Reference -| What you want | How to do it | +| Feature | Code Example | |---|---| -| Persist everything | `persist(myStore, {name: 'key'})` | -| Persist specific properties | `properties: ['count', 'name']` | -| Handle Dates | `{key: 'date', serialize: (date) => date.toISOString(), deserialize: (stored) => new Date(stored)}` | -| Handle ReactiveMap | `{key: 'map', serialize: (map) => [...map.entries()], deserialize: (stored) => reactiveMap(stored)}` | -| Debounce writes | `debounce: 500` | -| Migrate schema changes | `version: 2, migrate: (state, old) => { ... }` | -| SSR support | `skipHydration: true` + `handle.rehydrate()` in `useEffect` (safe to call at module scope) | -| Cross-tab sync | Enabled by default with `localStorage` | -| Disable cross-tab sync | `syncTabs: false` | -| Use sessionStorage | `storage: sessionStorage` | -| Use AsyncStorage | `storage: AsyncStorage, syncTabs: false` | -| Expire after 15 minutes | `expireIn: 900_000` | -| Auto-clear expired data | `clearOnExpire: true` | -| Check if data expired | `handle.isExpired` | -| Force immediate save | `handle.save()` | -| Clear stored data | `handle.clear()` | -| Stop persisting | `handle.unsubscribe()` | -| Wait for hydration | `await handle.hydrated` | -| Check hydration | `handle.isHydrated` | +| **Persist everything** | `persist(myStore, {name: 'key'})` | +| **Persist specific properties** | `properties: ['count', 'name']` | +| **Handle Dates & Objects** | `{key: 'date', serialize: (d) => d.toISOString(), deserialize: (s) => new Date(s)}` | +| **Handle Reactive collections** | `users: reactiveMap()` (supported natively) | +| **Use sessionStorage** | `storage: sessionStorage` | +| **Use AsyncStorage** | `storage: AsyncStorage, syncTabs: false` | +| **Disable cross-tab sync** | `syncTabs: false` | +| **Expire payload after time**| `expireIn: 900_000` | +| **Auto-clear expired data** | `clearOnExpire: true` | +| **SSR & manual hydration** | `skipHydration: true` + `handle.rehydrate()` | +| **Debounce storage writes**| `debounce: 500` | +| **Migrate schema versions**| `version: 2, migrate: (state, old) => { ... }` | +| **Merge strategy** | `merge: 'shallow'` \| `'replace'` \| `(persisted, current) => merged` | +| **Check hydration** | `handle.isHydrated` | +| **Wait for hydration** | `await handle.hydrated` | +| **Clear stored data** | `await handle.clear()` | +| **Force immediate save** | `await handle.save()` | +| **Re-hydrate manually** | `await handle.rehydrate()` | +| **Stop persisting** | `handle.unsubscribe()` | +| **Check if data expired** | `handle.isExpired` | diff --git a/website/docs/REACTIVE_COLLECTIONS_TUTORIAL.md b/website/docs/REACTIVE_COLLECTIONS_TUTORIAL.md new file mode 100644 index 0000000..4d2c3a1 --- /dev/null +++ b/website/docs/REACTIVE_COLLECTIONS_TUTORIAL.md @@ -0,0 +1,85 @@ +# Reactive Collections + +Classy Store provides `ReactiveMap` and `ReactiveSet` to help with persisting `Map` and `Set` collections. Both collections are backed by plain arrays under the hood, but they expose the exact same methods and APIs as their native counterparts. + +> [!NOTE] +> **Performance Tip:** You should use native `Map` and `Set` in the store for better performance in most cases. `ReactiveMap` and `ReactiveSet` should only be used if you explicitly need to persist a `Map` or `Set` to storage using the `persist()` utility. + +## Why Reactive Collections? + +Native `Map` and `Set` objects are not JSON-serializable by default, making them incompatible with `localStorage` and `sessionStorage`. When you `JSON.stringify` a `Map` or `Set`, it usually becomes an empty object `{}`. + +`ReactiveMap` and `ReactiveSet` are backed by internal structures that allow them to be persisted correctly when combined with the `serialize` and `deserialize` options in the `persist` utility. + +## Persisting a ReactiveMap + +When persisting a `ReactiveMap`, you do not need to provide custom `serialize` or `deserialize` logic. The reactive collection is backed by an internal structure the `persist` utility can natively stringify and parse. + +```ts +import {createClassyStore} from '@codebelt/classy-store'; +import {reactiveMap} from '@codebelt/classy-store/collections'; +import {persist} from '@codebelt/classy-store/utils'; + +class UserStore { + users = reactiveMap(); + + addUser(id: string, name: string, role: string) { + this.users.set(id, {name, role}); + } +} + +const userStore = createClassyStore(new UserStore()); + +persist(userStore, { + name: 'user-store', +}); +``` + +**What gets stored in storage:** + +```json +{ + "version": 0, + "state": { + "users": [ + ["u1", { "name": "Alice", "role": "admin" }], + ["u2", { "name": "Bob", "role": "viewer" }] + ] + } +} +``` + +## Persisting a ReactiveSet + +The same pattern works for `ReactiveSet`. You can simply stringify it by referring to the property directly. + +```ts +import {createClassyStore} from '@codebelt/classy-store'; +import {reactiveSet} from '@codebelt/classy-store/collections'; +import {persist} from '@codebelt/classy-store/utils'; + +class TagStore { + tags = reactiveSet(); + + addTag(tag: string) { + this.tags.add(tag); + } +} + +const tagStore = createClassyStore(new TagStore()); + +persist(tagStore, { + name: 'tag-store', +}); +``` + +**What gets stored in storage:** + +```json +{ + "version": 0, + "state": { + "tags": ["typescript", "javascript", "react"] + } +} +```