@t8/react-store 1.2.6 → 1.2.8

package/README.md

@@ -1,12 +1,10 @@
 # T8 React Store
 
-*Small React app state management lib aligned with React's state pattern, condensed to the essentials*
+React app state management condensed to the essentials
 
-[![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)
+[![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)
 
-**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, like Redux Toolkit, Zustand, Jotai, MobX, 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.
+**Features:** Quickest migration from local state · Familiar useState pattern · CSR/SSR without workarounds · Integrable with Immer · Quickly pluggable persistence across page reloads
 
 <!-- docsgen-show-start --
 ```diff
@@ -29,7 +27,7 @@ Installation: `npm i @t8/react-store`
 
 ## Shared state setup
 
-Moving the local state to the full-fledged shared state:
+Moving local state to the full-fledged shared state:
 
 ```diff
 + import { Store, useStore } from "@t8/react-store";
@@ -64,29 +62,29 @@ Moving the local state to the full-fledged shared state:
 [Live counter demo](https://codesandbox.io/p/sandbox/szhdnw?file=%252Fsrc%252FApp.tsx)<br>
 [Tic-tac-toe](https://codesandbox.io/p/sandbox/tq852v?file=%252Fsrc%252FApp.tsx)
 
-🔹 The shared state setup shown above is very similar to `useState()` allowing for quick migration from local state to shared state or the other way around.
+⬥ The shared state setup shown above is very similar to `useState()` allowing for quick migration from local state to shared state or the other way around.
 
-🔹 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.
+⬥ The optional `false` parameter in `useStore(store, false)` (as in `<ResetButton>` above) tells the hook not to subscribe the component to tracking the store updates. The common use case is when a component makes use of the store value setter without using the store 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.
+⬥ 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 the examples 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.
+⬥ 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
 
 An application can have as many stores as needed.
 
-🔹 Splitting data into multiple stores is one of the strategies to maintain more targeted subscriptions to data changes in components. The other strategy is filtering store updates at the component level, which is discussed below.
+⬥ Splitting data into multiple stores is one of the strategies to maintain more targeted subscriptions to data changes in components. The other strategy is filtering store updates at the component level, which is discussed below.
 
 ## Filtering store updates
 
-When only the store state setter is required, without the store state value, we can opt out from subscription to store state changes by passing `false` as the parameter of `useStore()`:
+When only the store value setter is required, without the store value, we can opt out from subscription to store changes by passing `false` as the parameter of `useStore()`:
 
 ```js
-let [, setState] = useState(store, false);
+let [, setValue] = useStore(store, false);
 ```
 
-Apart from a boolean, `useStore(store, shouldUpdate)` accepts a function of `(nextState, prevState) => boolean` as the optional second parameter to filter store updates to respond to:
+Apart from a boolean, `useStore(store, shouldUpdate)` accepts a function of `(nextValue, prevValue) => boolean` as the optional second parameter to filter store value updates to respond to:
 
 ```jsx
 import { useStore } from "@t8/react-store";
@@ -134,7 +132,7 @@ Shared state can be provided to the app by means of a regular React Context prov
 
 [Live counter demo with Context](https://codesandbox.io/p/sandbox/rtng37?file=%2Fsrc%2FPlusButton.jsx)
 
-🔹 In a multi-store setup, stores can be located in a single Context or split across multiple Contexts, just like any application data.
+⬥ In a multi-store setup, stores can be located in a single Context or split across multiple Contexts, just like any application data.
 
 ```jsx
 import { createContext, useContext } from "react";
@@ -153,11 +151,11 @@ let ItemCard = ({ id }) => {
 };
 ```
 
-🔹 Note that updating the store state doesn't change the store reference sitting in the React Context and therefore doesn't cause updates of the entire Context. Only the components subscribed to updates in the particular store by means of `useStore(store)` will be notified to re-render.
+⬥ Note that updating the store value doesn't change the store reference sitting in the React Context and therefore doesn't cause updates of the entire Context. Only the components subscribed to updates in the particular store by means of `useStore(store)` will be notified to re-render.
 
 ## Store data
 
-A store can contain data of any type. With TypeScript, the type of a store containing data of type `T` is `Store<T>` which can be inferred from `data` passed to `new Store(data)`.
+A store can contain data of any kind, whether of a primitive type or nonprimitive.
 
 Live demos:<br>
 [Primitive value state](https://codesandbox.io/p/sandbox/rtng37?file=%2Fsrc%2FPlusButton.jsx)<br>
@@ -171,7 +169,7 @@ Immer can be used with `useStore()` just the same way as [with `useState()`](htt
 
 ## Shared loading state
 
-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.
+The ready-to-use hook from [React Pending](https://github.com/t8js/react-pending) helps manage shared async action state without rearranging the app's state management and actions' code.
 
 ## Persistence across remounts
 
@@ -179,7 +177,7 @@ 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.
+Replacing `new Store(data)` with `new PersistentStore(data, storageKey)` as shown below gets the store's 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";
@@ -187,6 +185,6 @@ import { PersistentStore } from "@t8/react-store";
 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 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.
+⬥ 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.
+⬥ `PersistentStore` skips interaction with the browser storage in non-browser environments, which makes it equally usable with SSR.

package/dist/index.cjs

@@ -2,8 +2,8 @@ let __t8_store = require("@t8/store");
 let react = require("react");
 
 /**
-* Returns the state value of `store` passed as the parameter and
-* a function to update the store state value.
+* Returns the value of `store` passed as the parameter and a
+* function to update the store state value.
 *
 * @example
 * ```js
@@ -16,29 +16,29 @@ let react = require("react");
 *
 * `shouldUpdate` can be set to `false` to prevent subscription
 * to the store updates. Use case: if the component only requires
-* the store state setter but not the store state value, the
-* component may not need to respond to the store updates at all:
+* the store value setter but not the store value, the component
+* may not need to respond to the store updates at all:
 *
 * @example
 * ```js
 * let [, setValue] = useStore(store, false);
 * ```
 *
-* `shouldUpdate` can also be a function `(nextState, prevState) => boolean`
-* to make the component respond only to specific store state changes,
+* `shouldUpdate` can also be a function `(nextValue, prevValue) => boolean`
+* to make the component respond only to specific store value changes,
 * when this function returns `true`.
 */
 function useStore(store, shouldUpdate = true) {
   if (!(0, __t8_store.isStore)(store)) throw new Error("'store' is not an instance of Store");
   let [, setRevision] = (0, react.useState)(-1);
-  let state = store.getState();
-  let setState = (0, react.useMemo)(() => store.setState.bind(store), [store]);
+  let value = store.getValue();
+  let setValue = (0, react.useMemo)(() => store.setValue.bind(store), [store]);
   let initialStoreRevision = (0, react.useRef)(store.revision);
   (0, react.useEffect)(() => {
     if ((0, __t8_store.isPersistentStore)(store)) store.syncOnce();
     if (!shouldUpdate) return;
-    let unsubscribe = store.onUpdate((nextState, prevState) => {
-      if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState)) setRevision(Math.random());
+    let unsubscribe = store.onUpdate((nextValue, prevValue) => {
+      if (typeof shouldUpdate !== "function" || shouldUpdate(nextValue, prevValue)) setRevision(Math.random());
     });
     if (store.revision !== initialStoreRevision.current) setRevision(Math.random());
     return () => {
@@ -46,7 +46,7 @@ function useStore(store, shouldUpdate = true) {
       initialStoreRevision.current = store.revision;
     };
   }, [store, shouldUpdate]);
-  return [state, setState];
+  return [value, setValue];
 }
 
 exports.useStore = useStore;

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import { Store } from "@t8/store";
 export * from "@t8/store";
 
-type SetStoreState<T> = Store<T>["setState"];
-type ShouldUpdateCallback<T> = (nextState: T, prevState: T) => boolean;
+type SetStoreValue<T> = Store<T>["setValue"];
+type ShouldUpdateCallback<T> = (nextValue: T, prevValue: T) => boolean;
 type ShouldUpdate<T> = boolean | ShouldUpdateCallback<T>;
 /**
- * Returns the state value of `store` passed as the parameter and
- * a function to update the store state value.
+ * Returns the value of `store` passed as the parameter and a
+ * function to update the store state value.
  *
  * @example
  * ```js
@@ -19,18 +19,18 @@ type ShouldUpdate<T> = boolean | ShouldUpdateCallback<T>;
  *
  * `shouldUpdate` can be set to `false` to prevent subscription
  * to the store updates. Use case: if the component only requires
- * the store state setter but not the store state value, the
- * component may not need to respond to the store updates at all:
+ * the store value setter but not the store value, the component
+ * may not need to respond to the store updates at all:
  *
  * @example
  * ```js
  * let [, setValue] = useStore(store, false);
  * ```
  *
- * `shouldUpdate` can also be a function `(nextState, prevState) => boolean`
- * to make the component respond only to specific store state changes,
+ * `shouldUpdate` can also be a function `(nextValue, prevValue) => boolean`
+ * to make the component respond only to specific store value changes,
  * when this function returns `true`.
  */
-declare function useStore<T>(store: Store<T>, shouldUpdate?: ShouldUpdate<T>): [T, SetStoreState<T>];
+declare function useStore<T>(store: Store<T>, shouldUpdate?: ShouldUpdate<T>): [T, SetStoreValue<T>];
 
-export { SetStoreState, ShouldUpdate, ShouldUpdateCallback, useStore };
+export { SetStoreValue, ShouldUpdate, ShouldUpdateCallback, useStore };

package/dist/index.mjs

@@ -4,8 +4,8 @@ import { useEffect, useMemo, useRef, useState } from "react";
 export * from "@t8/store"
 
 /**
-* Returns the state value of `store` passed as the parameter and
-* a function to update the store state value.
+* Returns the value of `store` passed as the parameter and a
+* function to update the store state value.
 *
 * @example
 * ```js
@@ -18,29 +18,29 @@ export * from "@t8/store"
 *
 * `shouldUpdate` can be set to `false` to prevent subscription
 * to the store updates. Use case: if the component only requires
-* the store state setter but not the store state value, the
-* component may not need to respond to the store updates at all:
+* the store value setter but not the store value, the component
+* may not need to respond to the store updates at all:
 *
 * @example
 * ```js
 * let [, setValue] = useStore(store, false);
 * ```
 *
-* `shouldUpdate` can also be a function `(nextState, prevState) => boolean`
-* to make the component respond only to specific store state changes,
+* `shouldUpdate` can also be a function `(nextValue, prevValue) => boolean`
+* to make the component respond only to specific store value changes,
 * when this function returns `true`.
 */
 function useStore(store, shouldUpdate = true) {
   if (!isStore(store)) throw new Error("'store' is not an instance of Store");
   let [, setRevision] = useState(-1);
-  let state = store.getState();
-  let setState = useMemo(() => store.setState.bind(store), [store]);
+  let value = store.getValue();
+  let setValue = useMemo(() => store.setValue.bind(store), [store]);
   let initialStoreRevision = useRef(store.revision);
   useEffect(() => {
     if (isPersistentStore(store)) store.syncOnce();
     if (!shouldUpdate) return;
-    let unsubscribe = store.onUpdate((nextState, prevState) => {
-      if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState)) setRevision(Math.random());
+    let unsubscribe = store.onUpdate((nextValue, prevValue) => {
+      if (typeof shouldUpdate !== "function" || shouldUpdate(nextValue, prevValue)) setRevision(Math.random());
     });
     if (store.revision !== initialStoreRevision.current) setRevision(Math.random());
     return () => {
@@ -48,7 +48,7 @@ function useStore(store, shouldUpdate = true) {
       initialStoreRevision.current = store.revision;
     };
   }, [store, shouldUpdate]);
-  return [state, setState];
+  return [value, setValue];
 }
 
 export { useStore };

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@t8/react-store",
-  "version": "1.2.6",
-  "description": "Small React app state management lib aligned with React's state pattern, condensed to the essentials",
+  "version": "1.2.8",
+  "description": "React app state management condensed to the essentials",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "demo": "npx @t8/serve 3000 * tests/counter -b src/index.tsx",
+    "demo": "npx @t8/serve tests/counter --spa -b src/index.tsx",
+    "demo-t3": "npx @t8/serve tests/tic-tac-toe --spa -b src/index.tsx",
     "preversion": "npx npm-run-all shape test",
     "shape": "npx codeshape",
-    "test": "npx playwright test --project=chromium",
-    "tic-tac-toe": "npx @t8/serve 3000 * tests/tic-tac-toe -b src/index.tsx"
+    "test": "npx playwright test --project=chromium"
   },
   "repository": {
     "type": "git",
@@ -32,14 +32,14 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.56.0",
-    "@t8/serve": "^0.1.38",
+    "@t8/serve": "^0.2.0",
     "@types/node": "^24.5.2",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "immer": "^11.0.1",
-    "react-dom": "^19.2.1"
+    "react-dom": "^19.2.3"
   },
   "dependencies": {
-    "@t8/store": "^1.3.8"
+    "@t8/store": "^1.4.0"
   }
 }

package/src/useStore.ts

@@ -1,13 +1,13 @@
 import { isPersistentStore, isStore, type Store } from "@t8/store";
 import { useEffect, useMemo, useRef, useState } from "react";
 
-export type SetStoreState<T> = Store<T>["setState"];
-export type ShouldUpdateCallback<T> = (nextState: T, prevState: T) => boolean;
+export type SetStoreValue<T> = Store<T>["setValue"];
+export type ShouldUpdateCallback<T> = (nextValue: T, prevValue: T) => boolean;
 export type ShouldUpdate<T> = boolean | ShouldUpdateCallback<T>;
 
 /**
- * Returns the state value of `store` passed as the parameter and
- * a function to update the store state value.
+ * Returns the value of `store` passed as the parameter and a
+ * function to update the store state value.
  *
  * @example
  * ```js
@@ -20,29 +20,29 @@ export type ShouldUpdate<T> = boolean | ShouldUpdateCallback<T>;
  *
  * `shouldUpdate` can be set to `false` to prevent subscription
  * to the store updates. Use case: if the component only requires
- * the store state setter but not the store state value, the
- * component may not need to respond to the store updates at all:
+ * the store value setter but not the store value, the component
+ * may not need to respond to the store updates at all:
  *
  * @example
  * ```js
  * let [, setValue] = useStore(store, false);
  * ```
  *
- * `shouldUpdate` can also be a function `(nextState, prevState) => boolean`
- * to make the component respond only to specific store state changes,
+ * `shouldUpdate` can also be a function `(nextValue, prevValue) => boolean`
+ * to make the component respond only to specific store value changes,
  * when this function returns `true`.
  */
 export function useStore<T>(
   store: Store<T>,
   shouldUpdate: ShouldUpdate<T> = true,
-): [T, SetStoreState<T>] {
+): [T, SetStoreValue<T>] {
   if (!isStore<T>(store))
     throw new Error("'store' is not an instance of Store");
 
   let [, setRevision] = useState(-1);
 
-  let state = store.getState();
-  let setState = useMemo(() => store.setState.bind(store), [store]);
+  let value = store.getValue();
+  let setValue = useMemo(() => store.setValue.bind(store), [store]);
   let initialStoreRevision = useRef(store.revision);
 
   useEffect(() => {
@@ -50,10 +50,10 @@ export function useStore<T>(
 
     if (!shouldUpdate) return;
 
-    let unsubscribe = store.onUpdate((nextState, prevState) => {
+    let unsubscribe = store.onUpdate((nextValue, prevValue) => {
       if (
         typeof shouldUpdate !== "function" ||
-        shouldUpdate(nextState, prevState)
+        shouldUpdate(nextValue, prevValue)
       )
         setRevision(Math.random());
     });
@@ -67,5 +67,5 @@ export function useStore<T>(
     };
   }, [store, shouldUpdate]);
 
-  return [state, setState];
+  return [value, setValue];
 }