@t8/react-store 1.2.0 → 1.2.1

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
@@ -183,4 +183,6 @@ 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 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

@@ -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.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.3.2"
+    "@t8/store": "^1.3.3"
   }
 }