@apogeelabs/beacon-react-utils 0.2.0 → 1.0.0

package/README.md

@@ -1,5 +1,40 @@
 # Beacon/React Utilities
 
-This lib is experimental. We're still poking holes in it to see what we like and hate about it.
+This package provides some basic utilities to help bridge beacon stores with react hooks.
 
-If it survives our cynical skepticism, then docs will appear here. Until then, stay thirsty my friends.
+Right now it contains one helper hook: `useStoreWatcher`.
+
+## useStoreWatcher
+
+Normally, you would use the `observer` higher order function from mobx-react-lite to make components opt into mobx state changes. However, you can't use `observer` on a hook. If you have a situation where a stand-alone hook needs to react to changes in a beacon store, you can use `useStoreWatcher`.
+
+A basic example:
+
+```typescript
+useStoreWatcher<
+    CharitySelectionStoreState,
+    CharitySelectionStoreDerivedState,
+    CharitySelectionStoreActions,
+    Partial<CharitySearchArgs>
+>(
+    // first arg is the store you want to watch
+    charitySelectionStore,
+    // second arg is the selector that returns the state you want to watch for changes
+    state => {
+        return state.charitySearchParams;
+    },
+    // third arg is the "onChange" handler that should execute when the selector state changes
+    params => {
+        // Only update if the params actually changed
+        if (!isEqual(params, prevParamsRef.current)) {
+            prevParamsRef.current = params;
+            debouncedSetSearchParams(params);
+        }
+    },
+    // fourth arg is a `fireImmediately` boolean, indicating if the onChange call should execute
+    // immediately when the hook is called, or if it should wait until changes are observed later
+    true
+);
+```
+
+There are definitely other ways to go about this than to use this hook. For example, the component, if wrapped with `observer` can pass store state into a hook, and the hook can watch it via useEffect internally. (In fact, that's the 80% use case for these needs - this hook is just useful if you need to avoid prop drilling, or if it makes the particular intent more clear.)

package/dist/index.js

@@ -10,14 +10,16 @@ var ___default = /*#__PURE__*/_interopDefault(_);
 
 // src/useStoreWatcher.ts
 function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
+  const stableSelector = react.useEffectEvent(selector);
+  const stableOnChange = react.useEffectEvent(onChange);
   react.useEffect(() => {
     const disposer = mobx.reaction(
       () => {
-        return mobx.toJS(selector(store));
+        return mobx.toJS(stableSelector(store));
       },
       (value, previousValue) => {
         if (!previousValue || !___default.default.isEqual(value, previousValue)) {
-          onChange(value);
+          stableOnChange(value);
         }
       },
       { fireImmediately }
@@ -28,7 +30,7 @@ function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
     return () => {
       disposer();
     };
-  }, [store, selector, onChange, fireImmediately]);
+  }, [store, fireImmediately]);
 }
 
 exports.useStoreWatcher = useStoreWatcher;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,OAAO;AACd,SAAS,UAAU,YAAY;AAC/B,SAAS,iBAAiB;AAenB,SAAS,gBAMZ,OACA,UACA,UACA,kBAA2B,OACvB;AACJ,YAAU,MAAM;AAEZ,UAAM,WAAW;AAAA,MACb,MAAM;AAEF,eAAO,KAAK,SAAS,KAAK,CAAC;AAAA,MAC/B;AAAA,MACA,CAAC,OAAO,kBAAkB;AAEtB,YAAI,CAAC,iBAAiB,CAAC,EAAE,QAAQ,OAAO,aAAa,GAAG;AACpD,mBAAS,KAAK;AAAA,QAClB;AAAA,MACJ;AAAA,MACA,EAAE,gBAAgB;AAAA,IACtB;AAGA,UAAM,gBAAgB,MAAM;AACxB,eAAS;AAAA,IACb,CAAC;AAGD,WAAO,MAAM;AACT,eAAS;AAAA,IACb;AAAA,EACJ,GAAG,CAAC,OAAO,UAAU,UAAU,eAAe,CAAC;AACnD","sourcesContent":["import type { BeaconActions, BeaconDerived, BeaconState, Store } from \"@apogeelabs/beacon\";\nimport _ from \"lodash\";\nimport { reaction, toJS } from \"mobx\";\nimport { useEffect } from \"react\";\n\n/**\n * A custom React hook to watch for state changes in a beacon store.\n *\n * @template TState - The type of the store's state, extending BeaconState.\n * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.\n * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.\n * @template T - The type returned by the selector function, inferred from the selector.\n *\n * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.\n * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.\n * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.\n * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.\n */\nexport function useStoreWatcher<\n    TState extends BeaconState,\n    TDerived extends BeaconDerived<TState>,\n    TActions extends BeaconActions<TState>,\n    T,\n>(\n    store: Store<TState, TDerived, TActions>,\n    selector: (store: Store<TState, TDerived, TActions>) => T,\n    onChange: (value: T) => void,\n    fireImmediately: boolean = false\n): void {\n    useEffect(() => {\n        // Set up a MobX reaction to watch the selected state\n        const disposer = reaction(\n            () => {\n                // Convert to plain JS to strip MobX observable properties\n                return toJS(selector(store));\n            },\n            (value, previousValue) => {\n                // Only trigger if the value actually changed using deep comparison\n                if (!previousValue || !_.isEqual(value, previousValue)) {\n                    onChange(value);\n                }\n            },\n            { fireImmediately }\n        );\n\n        // Register the disposer with the store for cleanup\n        store.registerCleanup(() => {\n            disposer();\n        });\n\n        // Cleanup when the component unmounts or dependencies change\n        return () => {\n            disposer();\n        };\n    }, [store, selector, onChange, fireImmediately]);\n}\n\nexport default useStoreWatcher;\n"]}
+{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,OAAO;AACd,SAAS,UAAU,YAAY;AAC/B,SAAS,WAAW,sBAAsB;AAenC,SAAS,gBAMZ,OACA,UACA,UACA,kBAA2B,OACvB;AAGJ,QAAM,iBAAiB,eAAe,QAAQ;AAC9C,QAAM,iBAAiB,eAAe,QAAQ;AAE9C,YAAU,MAAM;AAEZ,UAAM,WAAW;AAAA,MACb,MAAM;AAEF,eAAO,KAAK,eAAe,KAAK,CAAC;AAAA,MACrC;AAAA,MACA,CAAC,OAAO,kBAAkB;AAEtB,YAAI,CAAC,iBAAiB,CAAC,EAAE,QAAQ,OAAO,aAAa,GAAG;AACpD,yBAAe,KAAK;AAAA,QACxB;AAAA,MACJ;AAAA,MACA,EAAE,gBAAgB;AAAA,IACtB;AAGA,UAAM,gBAAgB,MAAM;AACxB,eAAS;AAAA,IACb,CAAC;AAGD,WAAO,MAAM;AACT,eAAS;AAAA,IACb;AAAA,EACJ,GAAG,CAAC,OAAO,eAAe,CAAC;AAC/B","sourcesContent":["import type { BeaconActions, BeaconDerived, BeaconState, Store } from \"@apogeelabs/beacon\";\nimport _ from \"lodash\";\nimport { reaction, toJS } from \"mobx\";\nimport { useEffect, useEffectEvent } from \"react\";\n\n/**\n * A custom React hook to watch for state changes in a beacon store.\n *\n * @template TState - The type of the store's state, extending BeaconState.\n * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.\n * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.\n * @template T - The type returned by the selector function, inferred from the selector.\n *\n * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.\n * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.\n * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.\n * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.\n */\nexport function useStoreWatcher<\n    TState extends BeaconState,\n    TDerived extends BeaconDerived<TState>,\n    TActions extends BeaconActions<TState>,\n    T,\n>(\n    store: Store<TState, TDerived, TActions>,\n    selector: (store: Store<TState, TDerived, TActions>) => T,\n    onChange: (value: T) => void,\n    fireImmediately: boolean = false\n): void {\n    // Use useEffectEvent to wrap callbacks so they don't need to be in the dependency array\n    // This prevents unnecessary re-runs when consumers pass inline functions\n    const stableSelector = useEffectEvent(selector);\n    const stableOnChange = useEffectEvent(onChange);\n\n    useEffect(() => {\n        // Set up a MobX reaction to watch the selected state\n        const disposer = reaction(\n            () => {\n                // Convert to plain JS to strip MobX observable properties\n                return toJS(stableSelector(store));\n            },\n            (value, previousValue) => {\n                // Only trigger if the value actually changed using deep comparison\n                if (!previousValue || !_.isEqual(value, previousValue)) {\n                    stableOnChange(value);\n                }\n            },\n            { fireImmediately }\n        );\n\n        // Register the disposer with the store for cleanup\n        store.registerCleanup(() => {\n            disposer();\n        });\n\n        // Cleanup when the component unmounts or dependencies change\n        return () => {\n            disposer();\n        };\n    }, [store, fireImmediately]);\n}\n\nexport default useStoreWatcher;\n"]}

package/dist/index.mjs

@@ -1,17 +1,19 @@
 import _ from 'lodash';
 import { reaction, toJS } from 'mobx';
-import { useEffect } from 'react';
+import { useEffectEvent, useEffect } from 'react';
 
 // src/useStoreWatcher.ts
 function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
+  const stableSelector = useEffectEvent(selector);
+  const stableOnChange = useEffectEvent(onChange);
   useEffect(() => {
     const disposer = reaction(
       () => {
-        return toJS(selector(store));
+        return toJS(stableSelector(store));
       },
       (value, previousValue) => {
         if (!previousValue || !_.isEqual(value, previousValue)) {
-          onChange(value);
+          stableOnChange(value);
         }
       },
       { fireImmediately }
@@ -22,7 +24,7 @@ function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
     return () => {
       disposer();
     };
-  }, [store, selector, onChange, fireImmediately]);
+  }, [store, fireImmediately]);
 }
 
 export { useStoreWatcher };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,OAAO;AACd,SAAS,UAAU,YAAY;AAC/B,SAAS,iBAAiB;AAenB,SAAS,gBAMZ,OACA,UACA,UACA,kBAA2B,OACvB;AACJ,YAAU,MAAM;AAEZ,UAAM,WAAW;AAAA,MACb,MAAM;AAEF,eAAO,KAAK,SAAS,KAAK,CAAC;AAAA,MAC/B;AAAA,MACA,CAAC,OAAO,kBAAkB;AAEtB,YAAI,CAAC,iBAAiB,CAAC,EAAE,QAAQ,OAAO,aAAa,GAAG;AACpD,mBAAS,KAAK;AAAA,QAClB;AAAA,MACJ;AAAA,MACA,EAAE,gBAAgB;AAAA,IACtB;AAGA,UAAM,gBAAgB,MAAM;AACxB,eAAS;AAAA,IACb,CAAC;AAGD,WAAO,MAAM;AACT,eAAS;AAAA,IACb;AAAA,EACJ,GAAG,CAAC,OAAO,UAAU,UAAU,eAAe,CAAC;AACnD","sourcesContent":["import type { BeaconActions, BeaconDerived, BeaconState, Store } from \"@apogeelabs/beacon\";\nimport _ from \"lodash\";\nimport { reaction, toJS } from \"mobx\";\nimport { useEffect } from \"react\";\n\n/**\n * A custom React hook to watch for state changes in a beacon store.\n *\n * @template TState - The type of the store's state, extending BeaconState.\n * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.\n * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.\n * @template T - The type returned by the selector function, inferred from the selector.\n *\n * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.\n * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.\n * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.\n * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.\n */\nexport function useStoreWatcher<\n    TState extends BeaconState,\n    TDerived extends BeaconDerived<TState>,\n    TActions extends BeaconActions<TState>,\n    T,\n>(\n    store: Store<TState, TDerived, TActions>,\n    selector: (store: Store<TState, TDerived, TActions>) => T,\n    onChange: (value: T) => void,\n    fireImmediately: boolean = false\n): void {\n    useEffect(() => {\n        // Set up a MobX reaction to watch the selected state\n        const disposer = reaction(\n            () => {\n                // Convert to plain JS to strip MobX observable properties\n                return toJS(selector(store));\n            },\n            (value, previousValue) => {\n                // Only trigger if the value actually changed using deep comparison\n                if (!previousValue || !_.isEqual(value, previousValue)) {\n                    onChange(value);\n                }\n            },\n            { fireImmediately }\n        );\n\n        // Register the disposer with the store for cleanup\n        store.registerCleanup(() => {\n            disposer();\n        });\n\n        // Cleanup when the component unmounts or dependencies change\n        return () => {\n            disposer();\n        };\n    }, [store, selector, onChange, fireImmediately]);\n}\n\nexport default useStoreWatcher;\n"]}
+{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,OAAO;AACd,SAAS,UAAU,YAAY;AAC/B,SAAS,WAAW,sBAAsB;AAenC,SAAS,gBAMZ,OACA,UACA,UACA,kBAA2B,OACvB;AAGJ,QAAM,iBAAiB,eAAe,QAAQ;AAC9C,QAAM,iBAAiB,eAAe,QAAQ;AAE9C,YAAU,MAAM;AAEZ,UAAM,WAAW;AAAA,MACb,MAAM;AAEF,eAAO,KAAK,eAAe,KAAK,CAAC;AAAA,MACrC;AAAA,MACA,CAAC,OAAO,kBAAkB;AAEtB,YAAI,CAAC,iBAAiB,CAAC,EAAE,QAAQ,OAAO,aAAa,GAAG;AACpD,yBAAe,KAAK;AAAA,QACxB;AAAA,MACJ;AAAA,MACA,EAAE,gBAAgB;AAAA,IACtB;AAGA,UAAM,gBAAgB,MAAM;AACxB,eAAS;AAAA,IACb,CAAC;AAGD,WAAO,MAAM;AACT,eAAS;AAAA,IACb;AAAA,EACJ,GAAG,CAAC,OAAO,eAAe,CAAC;AAC/B","sourcesContent":["import type { BeaconActions, BeaconDerived, BeaconState, Store } from \"@apogeelabs/beacon\";\nimport _ from \"lodash\";\nimport { reaction, toJS } from \"mobx\";\nimport { useEffect, useEffectEvent } from \"react\";\n\n/**\n * A custom React hook to watch for state changes in a beacon store.\n *\n * @template TState - The type of the store's state, extending BeaconState.\n * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.\n * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.\n * @template T - The type returned by the selector function, inferred from the selector.\n *\n * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.\n * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.\n * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.\n * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.\n */\nexport function useStoreWatcher<\n    TState extends BeaconState,\n    TDerived extends BeaconDerived<TState>,\n    TActions extends BeaconActions<TState>,\n    T,\n>(\n    store: Store<TState, TDerived, TActions>,\n    selector: (store: Store<TState, TDerived, TActions>) => T,\n    onChange: (value: T) => void,\n    fireImmediately: boolean = false\n): void {\n    // Use useEffectEvent to wrap callbacks so they don't need to be in the dependency array\n    // This prevents unnecessary re-runs when consumers pass inline functions\n    const stableSelector = useEffectEvent(selector);\n    const stableOnChange = useEffectEvent(onChange);\n\n    useEffect(() => {\n        // Set up a MobX reaction to watch the selected state\n        const disposer = reaction(\n            () => {\n                // Convert to plain JS to strip MobX observable properties\n                return toJS(stableSelector(store));\n            },\n            (value, previousValue) => {\n                // Only trigger if the value actually changed using deep comparison\n                if (!previousValue || !_.isEqual(value, previousValue)) {\n                    stableOnChange(value);\n                }\n            },\n            { fireImmediately }\n        );\n\n        // Register the disposer with the store for cleanup\n        store.registerCleanup(() => {\n            disposer();\n        });\n\n        // Cleanup when the component unmounts or dependencies change\n        return () => {\n            disposer();\n        };\n    }, [store, fireImmediately]);\n}\n\nexport default useStoreWatcher;\n"]}

package/package.json

@@ -6,7 +6,7 @@
       "name": "Jim Cowart"
     }
   ],
-  "version": "0.2.0",
+  "version": "1.0.0",
   "license": "ISC",
   "description": "beacon middleware for react-query integration with beacon stores",
   "engines": {
@@ -39,13 +39,13 @@
   "dependencies": {
     "lodash": "4.17.16",
     "mobx": "^6.13.7",
-    "react": "^18.0.0",
-    "@apogeelabs/beacon": "0.4.1"
+    "react": "^19.2.3",
+    "@apogeelabs/beacon": "1.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.5",
     "@types/lodash": "4.17.16",
-    "@types/react": "^18.0.0",
+    "@types/react": "^19.2.3",
     "eslint": "^8.0.1",
     "eslint-config-standard": "^17.1.0",
     "eslint-plugin-import": "^2.25.2",