@t8/react-store 1.1.3 → 1.2.0

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 fill the gap with a state management lib that at the same time: (1) has a simple API introducing as few new entities as possible, (2) closely follows the React's `useState()` pattern of initializing and manipulating the state to fulfill the common task of migration from local state to shared state quickly without sizable rewrites, (3) doesn't internally make use of global stores or other global variables by default and works smoothly with SSR with regular React Contexts.
+
+**Features**: `useState()`-like API for shared state, quick transition from local state, no boilerplate, easily integrates with Immer, SSR- and CSR-compatible.
+
+<!-- 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,16 @@ 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.
+Whenever it's updated, `counterStore` above will save its state to the `"counter"` key of `localStorage`. (Pass `true` as the third parameter of `new PersistentStore()` to use `sessionStorage` instead of `localStorage`.) Also, the store's initial state value is restored from the browser storage. Otherwise, `counterStore` works pretty much like a regular store described above.

package/dist/index.js

@@ -1,76 +1,27 @@
 // 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);
+      this.callbacks.delete(callback);
     };
   }
-  off(event, callback) {
-    this.callbacks[event]?.delete(callback);
-  }
-  once(event, callback) {
-    let oneTimeCallback = (nextState, prevState) => {
-      this.off(event, oneTimeCallback);
-      callback(nextState, prevState);
-    };
-    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,77 @@ 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) {
+  if (typeof window === "undefined") return;
+  return session ? sessionStorage : localStorage;
+}
+var PersistentStore = class extends Store {
+  storageKey;
+  session;
+  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` if the `session` parameter is `false` (which is
+   * the default), or of `sessionStorage` if `session` is set to `true`.
+   * Interaction with the browser storage is skipped in non-browser environments.
+   *
+   * @example
+   * ```js
+   * let counterStore = new PersistentStore(0, "counter");
+   * ```
+   */
+  constructor(data, storageKey, session = false) {
+    super(data);
+    this.storageKey = storageKey;
+    this.session = session;
+    this.onUpdate(() => {
+      if (this.synced) this.save();
+    });
+  }
+  /**
+   * Saves the store state value to the browser storage.
+   */
+  save() {
+    let storage = getStorage(this.session);
+    if (this.synced && storage) {
+      try {
+        storage.setItem(this.storageKey, JSON.stringify(this.state));
+      } catch {
+      }
+    }
+  }
+  /**
+   * Signals the store to read the state value from the browser storage.
+   */
+  sync() {
+    let storage = getStorage(this.session);
+    let rawState = null;
+    if (storage) {
+      try {
+        rawState = storage.getItem(this.storageKey);
+        if (rawState !== null) this.setState(JSON.parse(rawState));
+      } catch {
+      }
+    }
+    if (!this.synced) {
+      this.synced = true;
+      if (rawState === 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 +113,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 +129,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.0",
   "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.2"
   }
 }

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)