@montra-interactive/deepstate-react 0.1.1

package/dist/hooks.d.ts

@@ -0,0 +1,135 @@
+import type { Observable } from "rxjs";
+/**
+ * Type helper to extract the value type from an Observable.
+ * Works with deepstate nodes since they extend Observable.
+ */
+type ObservableValue<T> = T extends Observable<infer V> ? V : never;
+/**
+ * Hook to subscribe to any Observable and get its current value.
+ * Re-renders the component whenever the observable emits a new value.
+ *
+ * Works with any RxJS Observable, including deepstate nodes.
+ *
+ * @param observable$ - Any RxJS Observable
+ * @param getSnapshot - Function to get the current value (required for plain observables)
+ * @returns The current value of the observable
+ *
+ * @example
+ * ```tsx
+ * import { useObservable } from 'deepstate-react';
+ * import { BehaviorSubject } from 'rxjs';
+ *
+ * const count$ = new BehaviorSubject(0);
+ *
+ * function Counter() {
+ *   const count = useObservable(count$, () => count$.getValue());
+ *   return <span>{count}</span>;
+ * }
+ * ```
+ */
+export declare function useObservable<T>(observable$: Observable<T>, getSnapshot: () => T): T;
+/**
+ * Hook to get the current value of a deepstate node.
+ * Re-renders the component whenever the node's value changes.
+ *
+ * This is the primary hook for using deepstate in React.
+ * Works with any deepstate node: RxLeaf, RxObject, RxArray, or RxNullable.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node (any reactive property from your state)
+ * @returns The current value of the node (deeply readonly)
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useStateValue } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [{ id: 1, name: 'Item 1' }],
+ *   count: 0
+ * });
+ *
+ * // Subscribe to a primitive
+ * function Counter() {
+ *   const count = useStateValue(store.count);
+ *   return <span>{count}</span>;
+ * }
+ *
+ * // Subscribe to an object
+ * function UserCard() {
+ *   const user = useStateValue(store.user);
+ *   return <div>{user.name}, {user.age}</div>;
+ * }
+ *
+ * // Subscribe to a nested property (fine-grained!)
+ * function UserName() {
+ *   const name = useStateValue(store.user.name);
+ *   return <span>{name}</span>;
+ * }
+ *
+ * // Subscribe to an array
+ * function ItemList() {
+ *   const items = useStateValue(store.items);
+ *   return <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export declare function useStateValue<T extends Observable<unknown>>(node: T): ObservableValue<T>;
+/**
+ * Hook to derive a value from a deepstate node with a selector function.
+ * Only re-renders when the derived value changes (using reference equality by default).
+ *
+ * Use this when you need to compute/transform a value from state.
+ * The selector runs on every emission but only triggers re-render if result changes.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node to select from
+ * @param selector - Function to derive a value from the node's value
+ * @param equalityFn - Optional custom equality function (default: Object.is)
+ * @returns The derived value
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useSelector } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { firstName: 'Alice', lastName: 'Smith', age: 30 },
+ *   items: [{ id: 1, price: 10 }, { id: 2, price: 20 }]
+ * });
+ *
+ * // Derive a computed value
+ * function FullName() {
+ *   const fullName = useSelector(
+ *     store.user,
+ *     user => `${user.firstName} ${user.lastName}`
+ *   );
+ *   return <span>{fullName}</span>;
+ * }
+ *
+ * // Derive from an array
+ * function TotalPrice() {
+ *   const total = useSelector(
+ *     store.items,
+ *     items => items.reduce((sum, item) => sum + item.price, 0)
+ *   );
+ *   return <span>Total: ${total}</span>;
+ * }
+ *
+ * // With custom equality (e.g., for arrays)
+ * function ItemIds() {
+ *   const ids = useSelector(
+ *     store.items,
+ *     items => items.map(i => i.id),
+ *     (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
+ *   );
+ *   return <span>{ids.join(', ')}</span>;
+ * }
+ * ```
+ */
+export declare function useSelector<T extends Observable<unknown>, R>(node: T, selector: (value: ObservableValue<T>) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export {};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAGvC;;;GAGG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAcpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC,EAC1B,WAAW,EAAE,MAAM,CAAC,GACnB,CAAC,CAkBH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EACzD,IAAI,EAAE,CAAC,GACN,eAAe,CAAC,CAAC,CAAC,CAuBpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,EAC1D,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,EAC1C,UAAU,GAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAmB,GAC9C,CAAC,CAuCH"}

package/dist/hooks.js

@@ -0,0 +1,181 @@
+import { useSyncExternalStore, useMemo, useCallback, useRef } from "react";
+import { map, distinctUntilChanged } from "rxjs/operators";
+function hasGet(obj) {
+    return obj !== null && typeof obj === "object" && "get" in obj && typeof obj.get === "function";
+}
+/**
+ * Hook to subscribe to any Observable and get its current value.
+ * Re-renders the component whenever the observable emits a new value.
+ *
+ * Works with any RxJS Observable, including deepstate nodes.
+ *
+ * @param observable$ - Any RxJS Observable
+ * @param getSnapshot - Function to get the current value (required for plain observables)
+ * @returns The current value of the observable
+ *
+ * @example
+ * ```tsx
+ * import { useObservable } from 'deepstate-react';
+ * import { BehaviorSubject } from 'rxjs';
+ *
+ * const count$ = new BehaviorSubject(0);
+ *
+ * function Counter() {
+ *   const count = useObservable(count$, () => count$.getValue());
+ *   return <span>{count}</span>;
+ * }
+ * ```
+ */
+export function useObservable(observable$, getSnapshot) {
+    const valueRef = useRef(getSnapshot());
+    const subscribe = useCallback((onStoreChange) => {
+        const subscription = observable$.subscribe((newValue) => {
+            valueRef.current = newValue;
+            onStoreChange();
+        });
+        return () => subscription.unsubscribe();
+    }, [observable$]);
+    const getSnapshotMemo = useCallback(() => valueRef.current, []);
+    return useSyncExternalStore(subscribe, getSnapshotMemo, getSnapshotMemo);
+}
+/**
+ * Hook to get the current value of a deepstate node.
+ * Re-renders the component whenever the node's value changes.
+ *
+ * This is the primary hook for using deepstate in React.
+ * Works with any deepstate node: RxLeaf, RxObject, RxArray, or RxNullable.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node (any reactive property from your state)
+ * @returns The current value of the node (deeply readonly)
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useStateValue } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [{ id: 1, name: 'Item 1' }],
+ *   count: 0
+ * });
+ *
+ * // Subscribe to a primitive
+ * function Counter() {
+ *   const count = useStateValue(store.count);
+ *   return <span>{count}</span>;
+ * }
+ *
+ * // Subscribe to an object
+ * function UserCard() {
+ *   const user = useStateValue(store.user);
+ *   return <div>{user.name}, {user.age}</div>;
+ * }
+ *
+ * // Subscribe to a nested property (fine-grained!)
+ * function UserName() {
+ *   const name = useStateValue(store.user.name);
+ *   return <span>{name}</span>;
+ * }
+ *
+ * // Subscribe to an array
+ * function ItemList() {
+ *   const items = useStateValue(store.items);
+ *   return <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export function useStateValue(node) {
+    // Ref to hold the current value - updated by subscription
+    const valueRef = useRef(hasGet(node) ? node.get() : undefined);
+    // Subscribe callback for useSyncExternalStore
+    const subscribe = useCallback((onStoreChange) => {
+        const subscription = node.subscribe((newValue) => {
+            valueRef.current = newValue;
+            onStoreChange();
+        });
+        return () => subscription.unsubscribe();
+    }, [node]);
+    // Get snapshot - just returns the ref value
+    const getSnapshot = useCallback(() => valueRef.current, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/**
+ * Hook to derive a value from a deepstate node with a selector function.
+ * Only re-renders when the derived value changes (using reference equality by default).
+ *
+ * Use this when you need to compute/transform a value from state.
+ * The selector runs on every emission but only triggers re-render if result changes.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node to select from
+ * @param selector - Function to derive a value from the node's value
+ * @param equalityFn - Optional custom equality function (default: Object.is)
+ * @returns The derived value
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useSelector } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { firstName: 'Alice', lastName: 'Smith', age: 30 },
+ *   items: [{ id: 1, price: 10 }, { id: 2, price: 20 }]
+ * });
+ *
+ * // Derive a computed value
+ * function FullName() {
+ *   const fullName = useSelector(
+ *     store.user,
+ *     user => `${user.firstName} ${user.lastName}`
+ *   );
+ *   return <span>{fullName}</span>;
+ * }
+ *
+ * // Derive from an array
+ * function TotalPrice() {
+ *   const total = useSelector(
+ *     store.items,
+ *     items => items.reduce((sum, item) => sum + item.price, 0)
+ *   );
+ *   return <span>Total: ${total}</span>;
+ * }
+ *
+ * // With custom equality (e.g., for arrays)
+ * function ItemIds() {
+ *   const ids = useSelector(
+ *     store.items,
+ *     items => items.map(i => i.id),
+ *     (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
+ *   );
+ *   return <span>{ids.join(', ')}</span>;
+ * }
+ * ```
+ */
+export function useSelector(node, selector, equalityFn = Object.is) {
+    // Create derived observable that applies selector and dedupes
+    const derived$ = useMemo(() => node.pipe(map((value) => selector(value)), distinctUntilChanged(equalityFn)), [node, selector, equalityFn]);
+    // Get initial derived value
+    const getInitialValue = () => {
+        if (hasGet(node)) {
+            return selector(node.get());
+        }
+        return undefined;
+    };
+    // Ref to hold the current derived value
+    const valueRef = useRef(getInitialValue());
+    // Subscribe callback for useSyncExternalStore
+    const subscribe = useCallback((onStoreChange) => {
+        const subscription = derived$.subscribe((newValue) => {
+            valueRef.current = newValue;
+            onStoreChange();
+        });
+        return () => subscription.unsubscribe();
+    }, [derived$]);
+    // Get snapshot - just returns the ref value
+    const getSnapshot = useCallback(() => valueRef.current, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * deepstate-react - React bindings for deepstate
+ *
+ * Provides hooks for using deepstate reactive state in React components.
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useStateValue, useSelector } from 'deepstate-react';
+ *
+ * const store = state({ user: { name: 'Alice', age: 30 }, count: 0 });
+ *
+ * function UserName() {
+ *   const name = useStateValue(store.user.name);
+ *   return <span>{name}</span>;
+ * }
+ *
+ * function UserSummary() {
+ *   const summary = useSelector(store.user, user => `${user.name} (${user.age})`);
+ *   return <span>{summary}</span>;
+ * }
+ * ```
+ */
+export { useStateValue, useSelector, useObservable, } from "./hooks";
+export type { Observable } from "rxjs";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,SAAS,CAAC;AAEjB,YAAY,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/hooks.ts
+import { useSyncExternalStore, useMemo, useCallback, useRef } from "react";
+import { map, distinctUntilChanged } from "rxjs/operators";
+function hasGet(obj) {
+  return obj !== null && typeof obj === "object" && "get" in obj && typeof obj.get === "function";
+}
+function useObservable(observable$, getSnapshot) {
+  const valueRef = useRef(getSnapshot());
+  const subscribe = useCallback((onStoreChange) => {
+    const subscription = observable$.subscribe((newValue) => {
+      valueRef.current = newValue;
+      onStoreChange();
+    });
+    return () => subscription.unsubscribe();
+  }, [observable$]);
+  const getSnapshotMemo = useCallback(() => valueRef.current, []);
+  return useSyncExternalStore(subscribe, getSnapshotMemo, getSnapshotMemo);
+}
+function useStateValue(node) {
+  const valueRef = useRef(hasGet(node) ? node.get() : undefined);
+  const subscribe = useCallback((onStoreChange) => {
+    const subscription = node.subscribe((newValue) => {
+      valueRef.current = newValue;
+      onStoreChange();
+    });
+    return () => subscription.unsubscribe();
+  }, [node]);
+  const getSnapshot = useCallback(() => valueRef.current, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useSelector(node, selector, equalityFn = Object.is) {
+  const derived$ = useMemo(() => node.pipe(map((value) => selector(value)), distinctUntilChanged(equalityFn)), [node, selector, equalityFn]);
+  const getInitialValue = () => {
+    if (hasGet(node)) {
+      return selector(node.get());
+    }
+    return;
+  };
+  const valueRef = useRef(getInitialValue());
+  const subscribe = useCallback((onStoreChange) => {
+    const subscription = derived$.subscribe((newValue) => {
+      valueRef.current = newValue;
+      onStoreChange();
+    });
+    return () => subscription.unsubscribe();
+  }, [derived$]);
+  const getSnapshot = useCallback(() => valueRef.current, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+export {
+  useStateValue,
+  useSelector,
+  useObservable
+};

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@montra-interactive/deepstate-react",
+  "version": "0.1.1",
+  "description": "React bindings for deepstate - Proxy-based reactive state management with RxJS.",
+  "keywords": [
+    "react",
+    "hooks",
+    "state",
+    "state-management",
+    "rxjs",
+    "reactive",
+    "observable",
+    "deepstate"
+  ],
+  "author": "Ronnie Magatti",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Montra-Interactive/deepstate",
+    "directory": "packages/react"
+  },
+  "module": "dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --external react --external rxjs --external deepstate && tsc -p tsconfig.build.json --emitDeclarationOnly"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "rxjs": "^7",
+    "deepstate": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.1",
+    "@types/jsdom": "^27.0.0",
+    "@types/react": "^19.2.8",
+    "deepstate": "workspace:*",
+    "jsdom": "^27.4.0",
+    "react": "^19.2.3"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,240 @@
+import { useSyncExternalStore, useMemo, useCallback, useRef } from "react";
+import type { Observable } from "rxjs";
+import { map, distinctUntilChanged } from "rxjs/operators";
+
+/**
+ * Type helper to extract the value type from an Observable.
+ * Works with deepstate nodes since they extend Observable.
+ */
+type ObservableValue<T> = T extends Observable<infer V> ? V : never;
+
+/**
+ * Interface for deepstate nodes that have a synchronous get() method.
+ * This is used internally to detect deepstate nodes vs plain observables.
+ */
+interface NodeWithGet<T> {
+  get(): T;
+}
+
+function hasGet<T>(obj: unknown): obj is NodeWithGet<T> {
+  return obj !== null && typeof obj === "object" && "get" in obj && typeof (obj as NodeWithGet<T>).get === "function";
+}
+
+/**
+ * Hook to subscribe to any Observable and get its current value.
+ * Re-renders the component whenever the observable emits a new value.
+ *
+ * Works with any RxJS Observable, including deepstate nodes.
+ *
+ * @param observable$ - Any RxJS Observable
+ * @param getSnapshot - Function to get the current value (required for plain observables)
+ * @returns The current value of the observable
+ *
+ * @example
+ * ```tsx
+ * import { useObservable } from 'deepstate-react';
+ * import { BehaviorSubject } from 'rxjs';
+ *
+ * const count$ = new BehaviorSubject(0);
+ *
+ * function Counter() {
+ *   const count = useObservable(count$, () => count$.getValue());
+ *   return <span>{count}</span>;
+ * }
+ * ```
+ */
+export function useObservable<T>(
+  observable$: Observable<T>,
+  getSnapshot: () => T
+): T {
+  const valueRef = useRef<T>(getSnapshot());
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const subscription = observable$.subscribe((newValue) => {
+        valueRef.current = newValue;
+        onStoreChange();
+      });
+
+      return () => subscription.unsubscribe();
+    },
+    [observable$]
+  );
+
+  const getSnapshotMemo = useCallback(() => valueRef.current, []);
+
+  return useSyncExternalStore(subscribe, getSnapshotMemo, getSnapshotMemo);
+}
+
+/**
+ * Hook to get the current value of a deepstate node.
+ * Re-renders the component whenever the node's value changes.
+ *
+ * This is the primary hook for using deepstate in React.
+ * Works with any deepstate node: RxLeaf, RxObject, RxArray, or RxNullable.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node (any reactive property from your state)
+ * @returns The current value of the node (deeply readonly)
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useStateValue } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { name: 'Alice', age: 30 },
+ *   items: [{ id: 1, name: 'Item 1' }],
+ *   count: 0
+ * });
+ *
+ * // Subscribe to a primitive
+ * function Counter() {
+ *   const count = useStateValue(store.count);
+ *   return <span>{count}</span>;
+ * }
+ *
+ * // Subscribe to an object
+ * function UserCard() {
+ *   const user = useStateValue(store.user);
+ *   return <div>{user.name}, {user.age}</div>;
+ * }
+ *
+ * // Subscribe to a nested property (fine-grained!)
+ * function UserName() {
+ *   const name = useStateValue(store.user.name);
+ *   return <span>{name}</span>;
+ * }
+ *
+ * // Subscribe to an array
+ * function ItemList() {
+ *   const items = useStateValue(store.items);
+ *   return <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export function useStateValue<T extends Observable<unknown>>(
+  node: T
+): ObservableValue<T> {
+  // Ref to hold the current value - updated by subscription
+  const valueRef = useRef<ObservableValue<T>>(
+    hasGet<ObservableValue<T>>(node) ? node.get() : (undefined as ObservableValue<T>)
+  );
+
+  // Subscribe callback for useSyncExternalStore
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const subscription = node.subscribe((newValue) => {
+        valueRef.current = newValue as ObservableValue<T>;
+        onStoreChange();
+      });
+
+      return () => subscription.unsubscribe();
+    },
+    [node]
+  );
+
+  // Get snapshot - just returns the ref value
+  const getSnapshot = useCallback(() => valueRef.current, []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Hook to derive a value from a deepstate node with a selector function.
+ * Only re-renders when the derived value changes (using reference equality by default).
+ *
+ * Use this when you need to compute/transform a value from state.
+ * The selector runs on every emission but only triggers re-render if result changes.
+ *
+ * Uses React 18's useSyncExternalStore for concurrent-mode safety.
+ *
+ * @param node - A deepstate node to select from
+ * @param selector - Function to derive a value from the node's value
+ * @param equalityFn - Optional custom equality function (default: Object.is)
+ * @returns The derived value
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useSelector } from 'deepstate-react';
+ *
+ * const store = state({
+ *   user: { firstName: 'Alice', lastName: 'Smith', age: 30 },
+ *   items: [{ id: 1, price: 10 }, { id: 2, price: 20 }]
+ * });
+ *
+ * // Derive a computed value
+ * function FullName() {
+ *   const fullName = useSelector(
+ *     store.user,
+ *     user => `${user.firstName} ${user.lastName}`
+ *   );
+ *   return <span>{fullName}</span>;
+ * }
+ *
+ * // Derive from an array
+ * function TotalPrice() {
+ *   const total = useSelector(
+ *     store.items,
+ *     items => items.reduce((sum, item) => sum + item.price, 0)
+ *   );
+ *   return <span>Total: ${total}</span>;
+ * }
+ *
+ * // With custom equality (e.g., for arrays)
+ * function ItemIds() {
+ *   const ids = useSelector(
+ *     store.items,
+ *     items => items.map(i => i.id),
+ *     (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
+ *   );
+ *   return <span>{ids.join(', ')}</span>;
+ * }
+ * ```
+ */
+export function useSelector<T extends Observable<unknown>, R>(
+  node: T,
+  selector: (value: ObservableValue<T>) => R,
+  equalityFn: (a: R, b: R) => boolean = Object.is
+): R {
+  // Create derived observable that applies selector and dedupes
+  const derived$ = useMemo(
+    () =>
+      node.pipe(
+        map((value) => selector(value as ObservableValue<T>)),
+        distinctUntilChanged(equalityFn)
+      ),
+    [node, selector, equalityFn]
+  );
+
+  // Get initial derived value
+  const getInitialValue = (): R => {
+    if (hasGet<ObservableValue<T>>(node)) {
+      return selector(node.get());
+    }
+    return undefined as R;
+  };
+
+  // Ref to hold the current derived value
+  const valueRef = useRef<R>(getInitialValue());
+
+  // Subscribe callback for useSyncExternalStore
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const subscription = derived$.subscribe((newValue) => {
+        valueRef.current = newValue;
+        onStoreChange();
+      });
+
+      return () => subscription.unsubscribe();
+    },
+    [derived$]
+  );
+
+  // Get snapshot - just returns the ref value
+  const getSnapshot = useCallback(() => valueRef.current, []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * deepstate-react - React bindings for deepstate
+ *
+ * Provides hooks for using deepstate reactive state in React components.
+ *
+ * @example
+ * ```tsx
+ * import { state } from 'deepstate';
+ * import { useStateValue, useSelector } from 'deepstate-react';
+ *
+ * const store = state({ user: { name: 'Alice', age: 30 }, count: 0 });
+ *
+ * function UserName() {
+ *   const name = useStateValue(store.user.name);
+ *   return <span>{name}</span>;
+ * }
+ *
+ * function UserSummary() {
+ *   const summary = useSelector(store.user, user => `${user.name} (${user.age})`);
+ *   return <span>{summary}</span>;
+ * }
+ * ```
+ */
+
+export {
+  useStateValue,
+  useSelector,
+  useObservable,
+} from "./hooks";
+
+export type { Observable } from "rxjs";