@t8/react-store 1.0.36 → 1.0.38

package/README.md

@@ -1,6 +1,6 @@
 # T8 React Store
 
-*Bare essentials for shared state management in React apps*
+*Small React app state management lib aligned with React's state pattern, 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)
 
@@ -20,8 +20,8 @@
 ```
 
 - Similar to `useState()`
-- No boilerplate
 - Quick transition from local state
+- No boilerplate
 - Easily integrates with Immer
 - SSR- and CSR-compatible
 
@@ -66,7 +66,7 @@ Moving the local state to the full-fledged shared state:
 
 🔹 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 `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 state updates. The common use case is when a component makes use of the store state setter without using the store state value.
 
 🔹 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.
 
@@ -84,19 +84,16 @@ When only the store state setter is required, without the store state value, we
 let [, setState] = useState(store, false);
 ```
 
-Apart from a boolean, `useStore(store, shouldUpdate)` accepts a function of `(nextState, prevState) => boolean` as the second parameter to filter store updates to respond to:
+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:
 
 ```jsx
 import { useStore } from "@t8/react-store";
 
 let ItemCard = ({ id }) => {
-  // Definition of changes in the item
-  let hasRelevantUpdates = useCallback((nextItems, prevItems) => {
+  let [items, setItems] = useStore(itemStore, (nextItems, prevItems) => {
     // Assuming that items have a `revision` property
     return nextItems[id].revision !== prevItems[id].revision;
-  }, [id]);
-
-  let [items, setItems] = useStore(itemStore, hasRelevantUpdates);
+  });
 
   return (
     // Content
@@ -104,6 +101,8 @@ 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
 
 Shared state can be provided to the app by means of a regular React Context provider:
@@ -156,7 +155,7 @@ let ItemCard = ({ id }) => {
 
 ## 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 the data passed to `new 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)`.
 
 Live demos:<br>
 [Primitive value state](https://codesandbox.io/p/sandbox/rtng37?file=%2Fsrc%2FPlusButton.jsx)<br>

package/dist/src/useStore.d.ts

@@ -2,24 +2,31 @@ import { type Store } from "@t8/store";
 export type SetStoreState<T> = Store<T>["setState"];
 export type ShouldUpdateCallback<T> = (nextState: T, prevState: T) => boolean;
 export type ShouldUpdate<T> = boolean | ShouldUpdateCallback<T>;
-export declare function useStore<T>(store: Store<T>, 
 /**
- * Controls whether the component should be updated in response
- * to the store updates.
+ * Returns the state value of `store` passed as the parameter and
+ * a function to update the store state value.
  *
- * @defaultValue `true`
+ * @example
+ * ```js
+ * let [value, setValue] = useStore(store);
+ * ```
+ *
+ * The optional second parameter `shouldUpdate` controls whether
+ * the component using this hook should be updated in response to
+ * the store updates, which is set to `true` by default.
  *
  * `shouldUpdate` can be set to `false` to prevent subscription
- * to the store updates. Use case: when the component only requires
+ * 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:
+ * component may not need to respond to the store updates at all:
  *
- * ```ts
+ * @example
+ * ```js
  * let [, setValue] = useStore(store, false);
  * ```
  *
- * `shouldUpdate` can be set to a function `(nextState, prevState) => boolean`
+ * `shouldUpdate` can also be a function `(nextState, prevState) => boolean`
  * to make the component respond only to specific store state changes,
  * when this function returns `true`.
  */
-shouldUpdate?: ShouldUpdate<T>): [T, SetStoreState<T>];
+export declare function useStore<T>(store: Store<T>, shouldUpdate?: ShouldUpdate<T>): [T, SetStoreState<T>];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@t8/react-store",
-  "version": "1.0.36",
-  "description": "Bare essentials for shared state management in React apps",
+  "version": "1.0.38",
+  "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",
   "type": "module",
@@ -11,11 +11,10 @@
     "compile": "npx esbuild index.ts --bundle --outdir=dist --platform=neutral --external:react",
     "demo": "npx @t8/serve 3000 * tests/counter -b src/index.tsx",
     "prepublishOnly": "npm run build",
-    "preversion": "npx npm-run-all typecheck shape build test",
-    "shape": "npx codeshape",
+    "preversion": "npx npm-run-all shape build test",
+    "shape": "npx codeshape --typecheck",
     "test": "npx playwright test --project=chromium",
     "tic-tac-toe": "npx @t8/serve 3000 * tests/tic-tac-toe -b src/index.tsx",
-    "typecheck": "tsc --noEmit",
     "types": "tsc -p tsconfig.build.json"
   },
   "repository": {
@@ -37,12 +36,12 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.56.0",
-    "@t8/serve": "^0.1.34",
+    "@t8/serve": "^0.1.36",
     "@types/node": "^24.5.2",
-    "@types/react": "^19.1.10",
-    "@types/react-dom": "^19.1.9",
-    "immer": "^10.1.3",
-    "react-dom": "^19.1.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "immer": "^11.0.1",
+    "react-dom": "^19.2.1",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/src/useStore.ts

@@ -5,27 +5,35 @@ export type SetStoreState<T> = Store<T>["setState"];
 export type ShouldUpdateCallback<T> = (nextState: T, prevState: 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.
+ *
+ * @example
+ * ```js
+ * let [value, setValue] = useStore(store);
+ * ```
+ *
+ * The optional second parameter `shouldUpdate` controls whether
+ * the component using this hook should be updated in response to
+ * the store updates, which is set to `true` by default.
+ *
+ * `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:
+ *
+ * @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,
+ * when this function returns `true`.
+ */
 export function useStore<T>(
   store: Store<T>,
-  /**
-   * Controls whether the component should be updated in response
-   * to the store updates.
-   *
-   * @defaultValue `true`
-   *
-   * `shouldUpdate` can be set to `false` to prevent subscription
-   * to the store updates. Use case: when 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:
-   *
-   * ```ts
-   * let [, setValue] = useStore(store, false);
-   * ```
-   *
-   * `shouldUpdate` can be set to a function `(nextState, prevState) => boolean`
-   * to make the component respond only to specific store state changes,
-   * when this function returns `true`.
-   */
   shouldUpdate: ShouldUpdate<T> = true,
 ): [T, SetStoreState<T>] {
   if (!isStore(store)) throw new Error("'store' is not an instance of Store");