@t8/react-store 1.2.0 → 1.2.2

package/README.md

@@ -4,9 +4,9 @@
 
 [![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.
+**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.
 
-**Features**: `useState()`-like API for shared state, quick transition from local state, no boilerplate, easily integrates with Immer, SSR- and CSR-compatible.
+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
@@ -68,6 +68,8 @@ Moving the local state to the full-fledged shared state:
 
 🔹 The optional `false` parameter in `useStore(store, false)` (as in `<ResetButton>` above) tells the hook not to subscribe the component to tracking the store state updates. The common use case is when a component makes use of the store state setter without using the store state value.
 
+🔹 With SSR, it's common practice to put shared values into React Context rather than module-level variables to avoid cross-request data sharing. The same applies to stores, see an example in the [Sharing state via Context](#sharing-state-via-context) section below.
+
 🔹 Similarly to instances of the built-in data container classes, such as `Set` and `Map`, stores are created as `new Store(data)` rather than with a factory function.
 
 ## Single store or multiple stores
@@ -103,7 +105,7 @@ let ItemCard = ({ id }) => {
 
 While `useStore(itemStore)` in this component would trigger a re-render in response to any changes in the `itemStore` (which can be fine with a small store), with `useStore(itemStore, shouldUpdate)` the `ItemCard` component has a more targeted subscription to the store: in this example, a re-render will only be triggered if the `revision` property of the item with the given `id` has changed.
 
-## Providing shared state
+## Sharing state via Context
 
 Shared state can be provided to the app by means of a regular React Context provider:
 
@@ -177,10 +179,14 @@ A standalone store initialized outside a component can be used by the component
 
 ## Persistence across page reloads
 
+Replacing `new Store(data)` with `new PersistentStore(data, storageKey)` as shown below gets the store's state value initially restored from and saved whenever updated to `storageKey` in `localStorage`. (Pass `{ session: true }` as the `options` parameter of `new PersistentStore(data, storageKey, options?)` to use `sessionStorage` instead of `localStorage`.) Otherwise, persistent stores work pretty much like regular stores described above.
+
 ```js
 import { PersistentStore } from "@t8/react-store";
 
 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 `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.
+🔹 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 redefined by setting `options.serialize` and `options.deserialize` in `new PersistentStore(data, storageKey, options?)`. By default, these options act like `JSON.stringify()` and `JSON.parse()` respectively.
+
+🔹 `PersistentStore` skips interaction with the browser storage in non-browser environments, which makes it equally usable with SSR.

package/dist/index.js

@@ -35,32 +35,43 @@ var Store = class {
 };
 
 // node_modules/@t8/store/src/PersistentStore.ts
-function getStorage(session) {
+function getStorage(session = false) {
   if (typeof window === "undefined") return;
   return session ? sessionStorage : localStorage;
 }
 var PersistentStore = class extends Store {
   storageKey;
-  session;
+  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` 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.
+   * 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, session = false) {
+  constructor(data, storageKey, options) {
     super(data);
     this.storageKey = storageKey;
-    this.session = session;
+    this.options = {
+      session: false,
+      serialize: (data2) => JSON.stringify(data2),
+      deserialize: (content) => JSON.parse(content),
+      ...options
+    };
     this.onUpdate(() => {
       if (this.synced) this.save();
     });
@@ -69,10 +80,11 @@ var PersistentStore = class extends Store {
    * Saves the store state value to the browser storage.
    */
   save() {
-    let storage = getStorage(this.session);
-    if (this.synced && storage) {
+    let storage = getStorage(this.options?.session);
+    let serialize = this.options?.serialize;
+    if (this.synced && storage && typeof serialize === "function") {
       try {
-        storage.setItem(this.storageKey, JSON.stringify(this.state));
+        storage.setItem(this.storageKey, serialize(this.state));
       } catch {
       }
     }
@@ -81,18 +93,20 @@ var PersistentStore = class extends Store {
    * Signals the store to read the state value from the browser storage.
    */
   sync() {
-    let storage = getStorage(this.session);
-    let rawState = null;
-    if (storage) {
+    let storage = getStorage(this.options?.session);
+    let deserialize = this.options?.deserialize;
+    let serializedState = null;
+    if (storage && typeof deserialize === "function") {
       try {
-        rawState = storage.getItem(this.storageKey);
-        if (rawState !== null) this.setState(JSON.parse(rawState));
+        serializedState = storage.getItem(this.storageKey);
+        if (serializedState !== null)
+          this.setState(deserialize(serializedState, this.state));
       } catch {
       }
     }
     if (!this.synced) {
       this.synced = true;
-      if (rawState === null) this.save();
+      if (serializedState === null) this.save();
     }
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t8/react-store",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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.3.2"
+    "@t8/store": "^1.3.3"
   }
 }