@apogeelabs/beacon-react-utils 0.1.1

package/LICENSE

@@ -0,0 +1,14 @@
+ISC License
+Copyright (c) 2025 Apogee Travel, LLC
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# Beacon/React Utilities
+
+This lib is experimental. We're still poking holes in it to see what we like and hate about it.
+
+If it survives our cynical skepticism, then docs will appear here. Until then, stay thirsty my friends.

package/dist/index.d.mts

@@ -0,0 +1,18 @@
+import { BeaconState, BeaconDerived, BeaconActions, Store } from '@apogeelabs/beacon';
+
+/**
+ * A custom React hook to watch for state changes in a beacon store.
+ *
+ * @template TState - The type of the store's state, extending BeaconState.
+ * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.
+ * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.
+ * @template T - The type returned by the selector function, inferred from the selector.
+ *
+ * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.
+ * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.
+ * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.
+ * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.
+ */
+declare function useStoreWatcher<TState extends BeaconState, TDerived extends BeaconDerived<TState>, TActions extends BeaconActions<TState>, T>(store: Store<TState, TDerived, TActions>, selector: (store: Store<TState, TDerived, TActions>) => T, onChange: (value: T) => void, fireImmediately?: boolean): void;
+
+export { useStoreWatcher };

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { BeaconState, BeaconDerived, BeaconActions, Store } from '@apogeelabs/beacon';
+
+/**
+ * A custom React hook to watch for state changes in a beacon store.
+ *
+ * @template TState - The type of the store's state, extending BeaconState.
+ * @template TDerived - The type of the store's derived values, extending BeaconDerived<TState>. If you don't have derived values, use EmptyDerived<TState>.
+ * @template TActions - The type of the store's actions, extending BeaconActions<TState>. If you don't have actions, use EmptyActions.
+ * @template T - The type returned by the selector function, inferred from the selector.
+ *
+ * @param {Store<TState, TDerived, TActions>} store - The Beacon store instance.
+ * @param {(store: Store<TState, TDerived, TActions>) => T} selector - A function that extracts the part of the store to watch.
+ * @param {(value: T) => void} onChange - A callback invoked with the new value when the selected state changes.
+ * @param {boolean} [fireImmediately=false] - Whether to invoke onChange with the initial value.
+ */
+declare function useStoreWatcher<TState extends BeaconState, TDerived extends BeaconDerived<TState>, TActions extends BeaconActions<TState>, T>(store: Store<TState, TDerived, TActions>, selector: (store: Store<TState, TDerived, TActions>) => T, onChange: (value: T) => void, fireImmediately?: boolean): void;
+
+export { useStoreWatcher };

package/dist/index.js

@@ -0,0 +1,36 @@
+'use strict';
+
+var isEqual = require('lodash/isEqual');
+var mobx = require('mobx');
+var react = require('react');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var isEqual__default = /*#__PURE__*/_interopDefault(isEqual);
+
+// src/useStoreWatcher.ts
+function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
+  react.useEffect(() => {
+    const disposer = mobx.reaction(
+      () => {
+        return mobx.toJS(selector(store));
+      },
+      (value, previousValue) => {
+        if (!previousValue || !isEqual__default.default(value, previousValue)) {
+          onChange(value);
+        }
+      },
+      { fireImmediately }
+    );
+    store.registerCleanup(() => {
+      disposer();
+    });
+    return () => {
+      disposer();
+    };
+  }, [store, selector, onChange, fireImmediately]);
+}
+
+exports.useStoreWatcher = useStoreWatcher;
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,aAAa;AACpB,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,QAAQ,OAAO,aAAa,GAAG;AAClD,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 isEqual from \"lodash/isEqual\";\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"]}

package/dist/index.mjs

@@ -0,0 +1,30 @@
+import isEqual from 'lodash/isEqual';
+import { reaction, toJS } from 'mobx';
+import { useEffect } from 'react';
+
+// src/useStoreWatcher.ts
+function useStoreWatcher(store, selector, onChange, fireImmediately = false) {
+  useEffect(() => {
+    const disposer = reaction(
+      () => {
+        return toJS(selector(store));
+      },
+      (value, previousValue) => {
+        if (!previousValue || !isEqual(value, previousValue)) {
+          onChange(value);
+        }
+      },
+      { fireImmediately }
+    );
+    store.registerCleanup(() => {
+      disposer();
+    });
+    return () => {
+      disposer();
+    };
+  }, [store, selector, onChange, fireImmediately]);
+}
+
+export { useStoreWatcher };
+//# sourceMappingURL=out.js.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useStoreWatcher.ts"],"names":[],"mappings":";AACA,OAAO,aAAa;AACpB,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,QAAQ,OAAO,aAAa,GAAG;AAClD,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 isEqual from \"lodash/isEqual\";\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"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@apogeelabs/beacon-react-utils",
+  "author": "Apogee Travel",
+  "contributors": [
+    {
+      "name": "Jim Cowart"
+    }
+  ],
+  "version": "0.1.1",
+  "license": "ISC",
+  "description": "beacon middleware for react-query integration with beacon stores",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "beacon",
+    "mobx",
+    "store",
+    "state management"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "lodash": "4.17.16",
+    "mobx": "^6.13.7",
+    "react": "^18.0.0",
+    "@apogeelabs/beacon": "0.4.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.5",
+    "@types/lodash": "4.17.16",
+    "@types/react": "^18.0.0",
+    "eslint": "^8.0.1",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.25.2",
+    "eslint-plugin-n": "^15.0.0 || ^16.0.0 ",
+    "eslint-plugin-promise": "^6.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "tsup": "^7.2.0",
+    "typescript": "^5.2.2"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "test": "jest",
+    "test:watch": "jest --watch --collect-coverage",
+    "lint": "eslint --config ../../.eslintrc.js 'src/**/*.{ts,tsx}'"
+  }
+}