@t8/react-store 1.1.3 → 1.2.1

package/README.md

@@ -4,6 +4,11 @@
 
 [![npm](https://img.shields.io/npm/v/@t8/react-store?labelColor=345&color=46e)](https://www.npmjs.com/package/@t8/react-store) ![Lightweight](https://img.shields.io/bundlephobia/minzip/@t8/react-store?label=minzip&labelColor=345&color=46e) ![CSR ✓](https://img.shields.io/badge/CSR-✓-345?labelColor=345) ![SSR ✓](https://img.shields.io/badge/SSR-✓-345?labelColor=345)
 
+**Why?** To have an easy-to-use state management lib for React apps requiring least effort to migrate from local state and to quickly set up shared state from scratch, whether with SSR or without. Other approaches, including Redux Toolkit, Zustand, Jotai, MobX, invariably depart from this picture to varying degrees.
+
+This picture is achieved here by (1) having a simple API introducing as few new entities as possible, (2) closely following the React's `useState()` pattern of initializing and manipulating the state to avoid boilerplate and sizable rewrites in the common task of migration from local state to shared state, (3) working smoothly with SSR with regular React Contexts without requiring a specifically designed setup and without internally making use of global stores or other global variables by default.
+
+<!-- docsgen-show-start --
 ```diff
 + let store = new Store(0);
 
@@ -18,12 +23,7 @@
     return <button onClick={handleClick}>+ {counter}</button>;
   };
 ```
-
-- Similar to `useState()`
-- Quick transition from local state
-- No boilerplate
-- Easily integrates with Immer
-- SSR- and CSR-compatible
+-- docsgen-show-end -->
 
 Installation: `npm i @t8/react-store`
 
@@ -171,16 +171,18 @@ Immer can be used with `useStore()` just the same way as [with `useState()`](htt
 
 The ready-to-use hook from the [T8 React Pending](https://github.com/t8js/react-pending) package helps manage shared async action state without disturbing the app's state management and actions' code.
 
-## Remount-persistent state
+## Persistence across remounts
 
 A standalone store initialized outside a component can be used by the component as remount-persistent state, whether used by other components or not.
 
 ## Persistence across page reloads
 
 ```js
-import { Store, persist } from "@t8/react-store";
+import { PersistentStore } from "@t8/react-store";
 
-let counterStore = persist(new Store(0), "counter");
+let counterStore = new PersistentStore(0, "counter");
 ```
 
-Whenever it's updated, `counterStore` above will save its state to the `"counter"` key of `localStorage`. (Pass `true` as the third parameter of `persist()` to use `sessionStorage` instead of `localStorage`.) `counterStore` returned from `persist()` is the same store passed as the first parameter enhanced to be persistent across page reloads.
+The store's state value is initially restored from and saved whenever updated to the `"counter"` key of `localStorage`. (Pass `{ session: true }` as the `options` parameter of `new PersistentStore(data, storageKey, options?)` to use `sessionStorage` instead of `localStorage`.) Otherwise, `counterStore` works pretty much like a regular store described above.
+
+The way data gets saved to and restored from a browser storage entry (including filtering out certain data or otherwise rearranging the saved data) can be overridden by setting `options.serialize` and `options.deserialize` in `new PersistentStore(data, storageKey, options?)`. By default, they are `JSON.stringify()` and `JSON.parse()`.

package/dist/index.js

@@ -1,75 +1,26 @@
 // node_modules/@t8/store/src/isStore.ts
 function isStore(x) {
-  return x !== null && typeof x === "object" && "on" in x && typeof x.on === "function" && "getState" in x && typeof x.getState === "function" && "setState" in x && typeof x.setState === "function";
+  return x !== null && typeof x === "object" && "onUpdate" in x && typeof x.onUpdate === "function" && "getState" in x && typeof x.getState === "function" && "setState" in x && typeof x.setState === "function";
 }
 
-// node_modules/@t8/store/src/persist.ts
-function getStorage(session) {
-  if (typeof window === "undefined") return;
-  return session ? sessionStorage : localStorage;
-}
-function persist(store, storageKey, session = false) {
-  let inited = false;
-  function read(state) {
-    let storage = getStorage(session);
-    let rawState = null;
-    if (storage) {
-      try {
-        rawState = storage.getItem(storageKey);
-        if (rawState !== null) store.setState(JSON.parse(rawState));
-      } catch {
-      }
-    }
-    if (!inited) {
-      inited = true;
-      if (rawState === null) write(state);
-    }
-  }
-  function write(state) {
-    let storage = getStorage(session);
-    if (inited && storage) {
-      try {
-        storage.setItem(storageKey, JSON.stringify(state));
-      } catch {
-      }
-    }
-  }
-  store.on("sync", read);
-  store.once("effect", read);
-  store.on("update", write);
-  return store;
+// node_modules/@t8/store/src/isPersistentStore.ts
+function isPersistentStore(x) {
+  return isStore(x) && "sync" in x;
 }
 
 // node_modules/@t8/store/src/Store.ts
 var Store = class {
   state;
-  callbacks = {};
+  callbacks = /* @__PURE__ */ new Set();
   revision = -1;
   constructor(data) {
     this.state = data;
   }
-  on(event, callback) {
-    (this.callbacks[event] ??= /* @__PURE__ */ new Set()).add(callback);
+  onUpdate(callback) {
+    this.callbacks.add(callback);
     return () => {
-      this.off(event, callback);
-    };
-  }
-  off(event, callback) {
-    this.callbacks[event]?.delete(callback);
-  }
-  once(event, callback) {
-    let oneTimeCallback = (nextState, prevState) => {
-      this.off(event, oneTimeCallback);
-      callback(nextState, prevState);
+      this.callbacks.delete(callback);
     };
-    return this.on(event, oneTimeCallback);
-  }
-  emit(event, nextState, prevState) {
-    let eventCallbacks = this.callbacks[event];
-    if (eventCallbacks) {
-      for (let callback of eventCallbacks)
-        callback(nextState ?? this.state, prevState ?? this.state);
-    }
   }
   getState() {
     return this.state;
@@ -79,7 +30,91 @@ var Store = class {
     let nextState = update instanceof Function ? update(this.state) : update;
     this.state = nextState;
     this.revision = Math.random();
-    this.emit("update", nextState, prevState);
+    for (let callback of this.callbacks) callback(nextState, prevState);
+  }
+};
+
+// node_modules/@t8/store/src/PersistentStore.ts
+function getStorage(session = false) {
+  if (typeof window === "undefined") return;
+  return session ? sessionStorage : localStorage;
+}
+var PersistentStore = class extends Store {
+  storageKey;
+  options;
+  synced = false;
+  /**
+   * Creates an instance of the container for data persistent across page
+   * reloads.
+   *
+   * The store data is saved to and restored from the given `storageKey`
+   * either of `localStorage` (by default) or `sessionStorage` (if `options.session`
+   * is set to `true`). Interaction with the browser storage is skipped in
+   * non-browser environments.
+   *
+   * @example
+   * ```js
+   * let counterStore = new PersistentStore(0, "counter");
+   * ```
+   *
+   * The way data gets saved to and restored from a browser storage entry
+   * (including filtering out certain data or otherwise rearranging the
+   * saved data) can be overridden by setting `options.serialize` and
+   * `options.deserialize`. By default, they are `JSON.stringify()` and
+   * `JSON.parse()`.
+   */
+  constructor(data, storageKey, options) {
+    super(data);
+    this.storageKey = storageKey;
+    this.options = {
+      session: false,
+      serialize: (data2) => JSON.stringify(data2),
+      deserialize: (content) => JSON.parse(content),
+      ...options
+    };
+    this.onUpdate(() => {
+      if (this.synced) this.save();
+    });
+  }
+  /**
+   * Saves the store state value to the browser storage.
+   */
+  save() {
+    let storage = getStorage(this.options?.session);
+    let serialize = this.options?.serialize;
+    if (this.synced && storage && typeof serialize === "function") {
+      try {
+        storage.setItem(this.storageKey, serialize(this.state));
+      } catch {
+      }
+    }
+  }
+  /**
+   * Signals the store to read the state value from the browser storage.
+   */
+  sync() {
+    let storage = getStorage(this.options?.session);
+    let deserialize = this.options?.deserialize;
+    let serializedState = null;
+    if (storage && typeof deserialize === "function") {
+      try {
+        serializedState = storage.getItem(this.storageKey);
+        if (serializedState !== null)
+          this.setState(deserialize(serializedState, this.state));
+      } catch {
+      }
+    }
+    if (!this.synced) {
+      this.synced = true;
+      if (serializedState === null) this.save();
+    }
+  }
+  /**
+   * Signals the store to read the state value from the browser storage once,
+   * disregarding subsequest `syncOnce()` calls.
+   */
+  syncOnce() {
+    if (!this.synced) this.sync();
   }
 };
 
@@ -92,9 +127,9 @@ function useStore(store, shouldUpdate = true) {
   let setState = useMemo(() => store.setState.bind(store), [store]);
   let initialStoreRevision = useRef(store.revision);
   useEffect(() => {
-    store.emit("effect");
+    if (isPersistentStore(store)) store.syncOnce();
     if (!shouldUpdate) return;
-    let unsubscribe = store.on("update", (nextState, prevState) => {
+    let unsubscribe = store.onUpdate((nextState, prevState) => {
       if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState))
         setRevision(Math.random());
     });
@@ -108,8 +143,9 @@ function useStore(store, shouldUpdate = true) {
   return [state, setState];
 }
 export {
+  PersistentStore,
   Store,
+  isPersistentStore,
   isStore,
-  persist,
   useStore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t8/react-store",
-  "version": "1.1.3",
+  "version": "1.2.1",
   "description": "Small React app state management lib aligned with React's state pattern, condensed to the essentials",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,6 +45,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@t8/store": "^1.2.3"
+    "@t8/store": "^1.3.3"
   }
 }

package/src/useStore.ts

@@ -1,4 +1,4 @@
-import { isStore, type Store } from "@t8/store";
+import { isPersistentStore, isStore, type Store } from "@t8/store";
 import { useEffect, useMemo, useRef, useState } from "react";
 
 export type SetStoreState<T> = Store<T>["setState"];
@@ -45,14 +45,11 @@ export function useStore<T>(
   let initialStoreRevision = useRef(store.revision);
 
   useEffect(() => {
-    // Use case: a one-time subscription to this event allows to
-    // initialize the store state on the client without causing a
-    // hydration error.
-    store.emit("effect");
+    if (isPersistentStore<T>(store)) store.syncOnce();
 
     if (!shouldUpdate) return;
 
-    let unsubscribe = store.on("update", (nextState, prevState) => {
+    let unsubscribe = store.onUpdate((nextState, prevState) => {
       if (
         typeof shouldUpdate !== "function" ||
         shouldUpdate(nextState, prevState)