chem-rx 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 - 2026-06-14
+
+### Added
+
+- `useSelector(atom, selector, equals?)` React hook (`chem-rx/react`): derive any
+  value from an atom with a selector function and re-render only when the selected
+  value changes. The optional `equals` comparator (defaults to `Object.is`) dedupes
+  re-renders by content, so an atom that churns references on every update only
+  re-renders the component when the selected slice is not equal. See
+  [useSelector](./README.md#useselector).
+
+### Removed (breaking)
+
+- Removed `useSelectAtom`. Migrate to `useSelector` with a selector function:
+  `useSelectAtom(atom, 'key')` becomes `useSelector(atom, (s) => s.key)`.
+
 ## 0.2.0 - 2026-06-13
 
 ### Added

package/README.md

@@ -389,25 +389,44 @@ function Counter() {
 
 Remember that you can mix and match for any of your needs
 
-### useSelectAtom
+### useSelector
 
-With `useSelectAtom` you can select a specific key from an atom, and still have it live
-update in your react component.
+With `useSelector` you can derive any value from an atom with a selector function, and
+have your component live update — re-rendering only when the selected value changes.
 
 ```
 import { Atom } from 'chem-rx'
-import { useSelectAtom } from 'chem-rx/react'
+import { useSelector } from 'chem-rx/react'
 
 const count$ = Atom({ inner: 0 })
 
 function Counter() {
-  const count = useSelectAtom(count$, 'inner')
+  const count = useSelector(count$, (s) => s.inner)
   return (
     <h1>
       {count}
         <button onClick={() => count$.set('inner', count + 2)}>one up</button> ...
 ```
 
+`useSelector` takes an optional `equals` comparator (defaulting to `Object.is`) so you
+can dedupe re-renders by content. This is the React-side counterpart to the atom-level
+`equals` option described in [Equality & change detection](#equality--change-detection):
+even if the parent atom rebuilds its value (and references) on every update, the
+component only re-renders when the selected slice is *not* equal.
+
+```
+const frame$ = Atom(initialFrame)
+
+const itemsEqual = (a, b) =>
+  a.length === b.length && a.every((v, i) => v === b[i])
+
+function ItemList() {
+  // re-renders only when `items` changes by content, not every frame
+  const items = useSelector(frame$, (f) => f.items, itemsEqual)
+  return <ul>{items.map((it) => <li key={it.id}>{it.label}</li>)}</ul>
+}
+```
+
 ### hydrateAtoms
 
 With SSR, your atoms will likely need to be properly hydrated to prevent

package/dist/react.cjs.js

@@ -38,13 +38,57 @@ function useSignal(signal, callback, id) {
   }, [signal, callback, id]);
 }
 
-function useSelectAtom(atom, key) {
-  var selectedAtom = react.useMemo(function () {
-    return atom.select(key);
-  }, [atom, key]);
-  return useAtom(selectedAtom);
+function createSelectorMemo(selector, equals) {
+  var hasValue = false;
+  var prevSnapshot;
+  var prevSelection;
+  return function (snapshot) {
+    if (hasValue && Object.is(prevSnapshot, snapshot)) {
+      return prevSelection;
+    }
+    var next = selector(snapshot);
+    if (hasValue && equals(prevSelection, next)) {
+      prevSnapshot = snapshot;
+      return prevSelection;
+    }
+    hasValue = true;
+    prevSnapshot = snapshot;
+    prevSelection = next;
+    return next;
+  };
+}
+
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+function useSelector(atom, selector, equals) {
+  if (equals === void 0) {
+    equals = Object.is;
+  }
+  var select = react.useMemo(function () {
+    return createSelectorMemo(selector, equals);
+  }, [selector, equals]);
+  return react.useSyncExternalStore(function (onStoreChange) {
+    var subscribed = false;
+    var subscription = atom.subscribe(function () {
+      if (subscribed) {
+        onStoreChange();
+      }
+    });
+    subscribed = true;
+    return function () {
+      subscription.unsubscribe();
+    };
+  }, function () {
+    return select(atom.value());
+  }, function () {
+    return select(atom.value());
+  });
 }
 
 exports.useAtom = useAtom;
-exports.useSelectAtom = useSelectAtom;
+exports.useSelector = useSelector;
 exports.useSignal = useSignal;

package/dist/react.d.ts

@@ -1,4 +1,4 @@
 export { useAtom } from "./useAtom";
 export { useSignal } from "./useSignal";
-export { useSelectAtom } from "./useSelectAtom";
+export { useSelector } from "./useSelector";
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/react.mjs

@@ -32,9 +32,46 @@ function useSignal(signal, callback, id) {
   }, [signal, callback, id]);
 }
 
-function useSelectAtom(atom, key) {
-  const selectedAtom = useMemo(() => atom.select(key), [atom, key]);
-  return useAtom(selectedAtom);
+function createSelectorMemo(selector, equals) {
+  let hasValue = false;
+  let prevSnapshot;
+  let prevSelection;
+  return snapshot => {
+    if (hasValue && Object.is(prevSnapshot, snapshot)) {
+      return prevSelection;
+    }
+    const next = selector(snapshot);
+    if (hasValue && equals(prevSelection, next)) {
+      prevSnapshot = snapshot;
+      return prevSelection;
+    }
+    hasValue = true;
+    prevSnapshot = snapshot;
+    prevSelection = next;
+    return next;
+  };
+}
+
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+function useSelector(atom, selector, equals = Object.is) {
+  const select = useMemo(() => createSelectorMemo(selector, equals), [selector, equals]);
+  return useSyncExternalStore(onStoreChange => {
+    let subscribed = false;
+    const subscription = atom.subscribe(() => {
+      if (subscribed) {
+        onStoreChange();
+      }
+    });
+    subscribed = true;
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, () => select(atom.value()), () => select(atom.value()));
 }
 
-export { useAtom, useSelectAtom, useSignal };
+export { useAtom, useSelector, useSignal };

package/dist/useSelector.d.ts

@@ -0,0 +1,10 @@
+import { Equals, ReadOnlyAtom } from "./Atom";
+export declare function createSelectorMemo<T, R>(selector: (value: T) => R, equals: Equals<R>): (snapshot: T) => R;
+/**
+ * Subscribe to a slice of an atom, re-rendering only when the selected value
+ * changes. The optional `equals` comparator dedupes by content (defaults to
+ * `Object.is`), so a parent atom that churns references every update will not
+ * re-render the component when the selected slice is content-equal.
+ */
+export declare function useSelector<T, R>(atom: ReadOnlyAtom<T>, selector: (value: T) => R, equals?: Equals<R>): R;
+//# sourceMappingURL=useSelector.d.ts.map

package/dist/useSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSelector.d.ts","sourceRoot":"","sources":["../src/useSelector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAkBpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,EAC9B,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EACzB,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAqBH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chem-rx",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "react state primitives with framework-agnostic atoms",
   "main": "dist/index.cjs.js",
   "module": "dist/index.mjs",
@@ -36,9 +36,14 @@
     "@babel/preset-typescript": "^7.22.5",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-node-resolve": "^15.1.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.3",
     "@types/react": "^18.2.20",
     "jest": "^29.6.2",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "rimraf": "^5.0.1",
     "rollup": "^3.28.0",
     "rollup-plugin-size-snapshot": "^0.12.0",

package/dist/useSelectAtom.d.ts

@@ -1,5 +0,0 @@
-import { BaseAtom, NullableBaseAtom, ReadOnlyAtom } from "./Atom";
-export declare function useSelectAtom<T extends {
-    [key in K]: V;
-}, K extends keyof T, V = T[K]>(atom: NullableBaseAtom<T> | BaseAtom<T> | ReadOnlyAtom<T>, key: K): T[K];
-//# sourceMappingURL=useSelectAtom.d.ts.map

package/dist/useSelectAtom.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useSelectAtom.d.ts","sourceRoot":"","sources":["../src/useSelectAtom.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGlE,wBAAgB,aAAa,CAC3B,CAAC,SACG;KACG,GAAG,IAAI,CAAC,GAAG,CAAC;CACd,EACL,CAAC,SAAS,MAAM,CAAC,EACjB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EACR,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAMzE"}