@t8/react-store 1.0.37 → 1.1.0

package/README.md

@@ -90,13 +90,10 @@ Apart from a boolean, `useStore(store, shouldUpdate)` accepts a function of `(ne
 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,7 +101,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, hasRelevantUpdates)` the `ItemCard` component has a more targeted subscription to the store: a re-render will only be triggered if the `revision` property of the item with the given `id` has changed.
+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
 

package/dist/index.js

@@ -1,22 +1,39 @@
 // node_modules/@t8/store/src/isStore.ts
 function isStore(x) {
-  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";
+  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";
 }
 
 // node_modules/@t8/store/src/Store.ts
 var Store = class {
   state;
-  callbacks = /* @__PURE__ */ new Set();
+  callbacks = {};
   revision = -1;
   constructor(data) {
     this.state = data;
   }
-  onUpdate(callback) {
-    this.callbacks.add(callback);
+  on(event, callback) {
+    (this.callbacks[event] ??= /* @__PURE__ */ new Set()).add(callback);
     return () => {
-      this.callbacks.delete(callback);
+      this.off(event, 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;
   }
@@ -25,7 +42,7 @@ var Store = class {
     let nextState = update instanceof Function ? update(this.state) : update;
     this.state = nextState;
     this.revision = Math.random();
-    for (let callback of this.callbacks) callback(nextState, prevState);
+    this.emit("update", nextState, prevState);
   }
 };
 
@@ -38,8 +55,9 @@ function useStore(store, shouldUpdate = true) {
   let setState = useMemo(() => store.setState.bind(store), [store]);
   let initialStoreRevision = useRef(store.revision);
   useEffect(() => {
+    store.emit("effect");
     if (!shouldUpdate) return;
-    let unsubscribe = store.onUpdate((nextState, prevState) => {
+    let unsubscribe = store.on("update", (nextState, prevState) => {
       if (typeof shouldUpdate !== "function" || shouldUpdate(nextState, prevState))
         setRevision(Math.random());
     });

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,6 +1,6 @@
 {
   "name": "@t8/react-store",
-  "version": "1.0.37",
+  "version": "1.1.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",
@@ -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,15 +36,15 @@
   },
   "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": {
-    "@t8/store": "^1.1.10"
+    "@t8/store": "^1.2.0"
   }
 }

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");
@@ -37,9 +45,14 @@ 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 (!shouldUpdate) return;
 
-    let unsubscribe = store.onUpdate((nextState, prevState) => {
+    let unsubscribe = store.on("update", (nextState, prevState) => {
       if (
         typeof shouldUpdate !== "function" ||
         shouldUpdate(nextState, prevState)