@montra-interactive/deepstate-react 0.2.3 → 0.2.5

package/README.md

@@ -0,0 +1,374 @@
+# @montra-interactive/deepstate-react
+
+React bindings for [deepstate](https://www.npmjs.com/package/@montra-interactive/deepstate) - proxy-based reactive state management with RxJS.
+
+## Features
+
+- **Fine-grained subscriptions**: Subscribe to any nested property
+- **Concurrent mode safe**: Uses `useSyncExternalStore` for React 18+
+- **Type-safe**: Full TypeScript support with inferred types
+- **RxJS integration**: Use `usePipeSelect` for debouncing, filtering, mapping
+- **Multiple node combining**: Array form (tuple) or object form (named keys)
+- **Custom equality**: Prevent unnecessary re-renders with custom comparators
+
+## Installation
+
+```bash
+npm install @montra-interactive/deepstate @montra-interactive/deepstate-react rxjs
+# or
+bun add @montra-interactive/deepstate @montra-interactive/deepstate-react rxjs
+# or
+yarn add @montra-interactive/deepstate @montra-interactive/deepstate-react rxjs
+```
+
+## Quick Start
+
+```tsx
+import { state } from "@montra-interactive/deepstate";
+import { useSelect } from "@montra-interactive/deepstate-react";
+
+// Create your store
+const store = state({
+  user: { name: "Alice", age: 30 },
+  count: 0,
+});
+
+// Use in components
+function UserName() {
+  const name = useSelect(store.user.name);
+  return <span>{name}</span>;
+}
+
+function Counter() {
+  const count = useSelect(store.count);
+  return (
+    <button onClick={() => store.count.set(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+## API Reference
+
+### `useSelect` - Subscribe to Deepstate Nodes
+
+The primary hook for using deepstate in React. Returns the current value and re-renders when it changes.
+
+#### Single Node
+
+```tsx
+const value = useSelect(store.user.name);  // string
+const user = useSelect(store.user);        // { name: string, age: number }
+```
+
+#### With Selector
+
+Transform the value before returning. Only re-renders when the derived value changes.
+
+```tsx
+const fullName = useSelect(
+  store.user,
+  user => `${user.firstName} ${user.lastName}`
+);
+
+const adultCount = useSelect(
+  store.users,
+  users => users.filter(u => u.age >= 18).length
+);
+```
+
+#### Multiple Nodes (Array Form)
+
+Combine multiple nodes into a single derived value:
+
+```tsx
+const percentage = useSelect(
+  [store.stats.completed, store.stats.total],
+  ([completed, total]) => total > 0 ? (completed / total) * 100 : 0
+);
+```
+
+#### Multiple Nodes (Object Form)
+
+Same as array form, but with named keys:
+
+```tsx
+const summary = useSelect(
+  { 
+    name: store.user.name, 
+    completed: store.stats.completed 
+  },
+  ({ name, completed }) => `${name} completed ${completed} tasks`
+);
+```
+
+#### Custom Equality Function
+
+Prevent re-renders with a custom equality check:
+
+```tsx
+const ids = useSelect(
+  store.items,
+  items => items.map(i => i.id),
+  // Custom array equality
+  (a, b) => a.length === b.length && a.every((v, i) => v === b[i])
+);
+```
+
+### `usePipeSelect` - Subscribe to Piped Observables
+
+For observables transformed with RxJS operators. Returns `T | undefined` because the stream might not have emitted yet.
+
+#### Debouncing
+
+Reduce re-renders from high-frequency updates:
+
+```tsx
+import { debounceTime } from "rxjs";
+
+function DebouncedSearch() {
+  const query = usePipeSelect(
+    store.searchQuery.pipe(debounceTime(300))
+  );
+  
+  if (query === undefined) {
+    return <span>Type to search...</span>;
+  }
+  
+  return <SearchResults query={query} />;
+}
+```
+
+#### Filtering
+
+Only emit when conditions are met:
+
+```tsx
+import { filter } from "rxjs";
+
+function PositiveOnly() {
+  const value = usePipeSelect(
+    store.count.pipe(filter(v => v > 0))
+  );
+  
+  // undefined until count > 0
+  return <span>{value ?? "Waiting for positive..."}</span>;
+}
+```
+
+#### Mapping / Transforming
+
+Transform values in the stream:
+
+```tsx
+import { map } from "rxjs";
+
+function TotalDuration() {
+  const total = usePipeSelect(
+    store.clips.pipe(
+      map(clips => clips.reduce((sum, c) => sum + c.duration, 0))
+    )
+  );
+  
+  return <span>Total: {total ?? 0}ms</span>;
+}
+```
+
+#### Combined Operators
+
+Chain multiple operators:
+
+```tsx
+import { debounceTime, filter, map } from "rxjs";
+
+function SmartSearch() {
+  const query = usePipeSelect(
+    store.searchQuery.pipe(
+      debounceTime(300),
+      filter(q => q.length >= 2),
+      map(q => q.trim().toLowerCase())
+    )
+  );
+  
+  if (query === undefined) {
+    return <span>Type at least 2 characters...</span>;
+  }
+  
+  return <SearchResults query={query} />;
+}
+```
+
+### `useObservable` - Low-level Observable Hook
+
+For any RxJS Observable when you need to provide the initial value getter:
+
+```tsx
+import { BehaviorSubject } from "rxjs";
+
+const count$ = new BehaviorSubject(0);
+
+function Counter() {
+  const count = useObservable(count$, () => count$.getValue());
+  return <span>{count}</span>;
+}
+```
+
+## Why Two Hooks?
+
+### The Sync/Async Boundary
+
+deepstate is a **synchronous store** backed by **reactive streams**:
+
+- `useSelect(store.x)` - Node has `.get()`, initial value always available. Returns `T`.
+- `usePipeSelect(store.x.pipe(...))` - Piped stream has no sync value. Returns `T | undefined`.
+
+When you `.pipe()` a node, you enter the async world of RxJS where:
+
+| Operator | Why No Sync Value? |
+|----------|-------------------|
+| `debounceTime(300)` | Waits 300ms before emitting |
+| `filter(v => v > 0)` | If value is `0`, nothing passed yet |
+| `switchMap(...)` | Depends on async operation |
+
+The `T | undefined` return type is **honest** - it forces you to handle the "not yet" case:
+
+```tsx
+// useSelect - always has value
+const count = useSelect(store.count);
+const doubled = count * 2;  // Safe
+
+// usePipeSelect - might be undefined
+const filtered = usePipeSelect(store.count.pipe(filter(v => v > 0)));
+const doubled = (filtered ?? 0) * 2;  // Must handle undefined
+```
+
+## Type Exports
+
+```ts
+import type { DeepstateNode } from "@montra-interactive/deepstate-react";
+```
+
+| Type | Description |
+|------|-------------|
+| `DeepstateNode<T>` | Observable with `.get()` - what `useSelect` accepts |
+
+## Full Type Signatures
+
+```ts
+// useSelect overloads
+function useSelect<T>(node: DeepstateNode<T>): T;
+
+function useSelect<T, R>(
+  node: DeepstateNode<T>,
+  selector: (value: T) => R,
+  equalityFn?: (a: R, b: R) => boolean
+): R;
+
+function useSelect<T1, T2, R>(
+  nodes: [DeepstateNode<T1>, DeepstateNode<T2>],
+  selector: (values: [T1, T2]) => R,
+  equalityFn?: (a: R, b: R) => boolean
+): R;
+
+// ... up to 5 nodes supported
+
+function useSelect<T extends Record<string, DeepstateNode<unknown>>, R>(
+  nodes: T,
+  selector: (values: { [K in keyof T]: /* inferred */ }) => R,
+  equalityFn?: (a: R, b: R) => boolean
+): R;
+
+// usePipeSelect
+function usePipeSelect<T>(piped$: Observable<T>): T | undefined;
+
+// useObservable
+function useObservable<T>(
+  observable$: Observable<T>,
+  getSnapshot: () => T
+): T;
+```
+
+## Common Patterns
+
+### Debounced Search Input
+
+```tsx
+function SearchBox() {
+  // Controlled input - immediate updates
+  const rawQuery = useSelect(store.searchQuery);
+  
+  // Debounced for expensive operations
+  const debouncedQuery = usePipeSelect(
+    store.searchQuery.pipe(debounceTime(300))
+  );
+  
+  return (
+    <div>
+      <input
+        value={rawQuery}
+        onChange={e => store.searchQuery.set(e.target.value)}
+      />
+      {debouncedQuery !== undefined && (
+        <SearchResults query={debouncedQuery} />
+      )}
+    </div>
+  );
+}
+```
+
+### Computing Totals
+
+```tsx
+function CartTotal() {
+  const total = usePipeSelect(
+    store.cart.items.pipe(
+      map(items => items.reduce((sum, i) => sum + i.price * i.qty, 0))
+    )
+  );
+  
+  return <span>${(total ?? 0).toFixed(2)}</span>;
+}
+```
+
+### Conditional Rendering
+
+```tsx
+function ValidUser() {
+  const user = usePipeSelect(
+    store.user.pipe(filter(u => u.name.length > 0))
+  );
+  
+  if (user === undefined) {
+    return <span>Please enter your name</span>;
+  }
+  
+  return <Profile user={user} />;
+}
+```
+
+### Preventing Re-renders
+
+```tsx
+// Only re-render when age changes, not name
+function UserAge() {
+  const age = useSelect(store.user, u => u.age);
+  return <span>{age}</span>;
+}
+
+// Or subscribe directly to the property
+function UserAge() {
+  const age = useSelect(store.user.age);
+  return <span>{age}</span>;
+}
+```
+
+## Peer Dependencies
+
+- `react` ^18 || ^19
+- `rxjs` ^7
+- `@montra-interactive/deepstate` ^0.2.0
+
+## License
+
+MIT

package/dist/hooks.d.ts

@@ -1,15 +1,16 @@
 import type { Observable } from "rxjs";
 /**
- * Type helper to extract the value type from an Observable.
- * Works with deepstate nodes since they extend Observable.
+ * Interface for deepstate nodes that have a synchronous get() method.
+ * This is used internally to detect deepstate nodes vs plain observables.
  */
-type ObservableValue<T> = T extends Observable<infer V> ? V : never;
+interface NodeWithGet<T> {
+    get(): T;
+}
 /**
- * Type for object of observables -> object of their values
+ * A deepstate node - an Observable that also has a synchronous get() method.
+ * Used to enforce that useSelect only accepts deepstate nodes, not piped observables.
  */
-type ObservableObjectValues<T extends Record<string, Observable<unknown>>> = {
-    [K in keyof T]: ObservableValue<T[K]>;
-};
+export type DeepstateNode<T> = Observable<T> & NodeWithGet<T>;
 /**
  * Hook to subscribe to any Observable and get its current value.
  * Re-renders the component whenever the observable emits a new value.
@@ -118,13 +119,15 @@ export declare function useObservable<T>(observable$: Observable<T>, getSnapshot
  * }
  * ```
  */
-export declare function useSelect<T extends Observable<unknown>>(node: T): ObservableValue<T>;
-export declare function useSelect<T extends Observable<unknown>, R>(node: T, selector: (value: ObservableValue<T>) => R, equalityFn?: (a: R, b: R) => boolean): R;
-export declare function useSelect<T1 extends Observable<unknown>, T2 extends Observable<unknown>, R>(nodes: [T1, T2], selector: (values: [ObservableValue<T1>, ObservableValue<T2>]) => R, equalityFn?: (a: R, b: R) => boolean): R;
-export declare function useSelect<T1 extends Observable<unknown>, T2 extends Observable<unknown>, T3 extends Observable<unknown>, R>(nodes: [T1, T2, T3], selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>]) => R, equalityFn?: (a: R, b: R) => boolean): R;
-export declare function useSelect<T1 extends Observable<unknown>, T2 extends Observable<unknown>, T3 extends Observable<unknown>, T4 extends Observable<unknown>, R>(nodes: [T1, T2, T3, T4], selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>, ObservableValue<T4>]) => R, equalityFn?: (a: R, b: R) => boolean): R;
-export declare function useSelect<T1 extends Observable<unknown>, T2 extends Observable<unknown>, T3 extends Observable<unknown>, T4 extends Observable<unknown>, T5 extends Observable<unknown>, R>(nodes: [T1, T2, T3, T4, T5], selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>, ObservableValue<T4>, ObservableValue<T5>]) => R, equalityFn?: (a: R, b: R) => boolean): R;
-export declare function useSelect<T extends Record<string, Observable<unknown>>, R>(nodes: T, selector: (values: ObservableObjectValues<T>) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T>(node: DeepstateNode<T>): T;
+export declare function useSelect<T, R>(node: DeepstateNode<T>, selector: (value: T) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T1, T2, R>(nodes: [DeepstateNode<T1>, DeepstateNode<T2>], selector: (values: [T1, T2]) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T1, T2, T3, R>(nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>], selector: (values: [T1, T2, T3]) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T1, T2, T3, T4, R>(nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>, DeepstateNode<T4>], selector: (values: [T1, T2, T3, T4]) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T1, T2, T3, T4, T5, R>(nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>, DeepstateNode<T4>, DeepstateNode<T5>], selector: (values: [T1, T2, T3, T4, T5]) => R, equalityFn?: (a: R, b: R) => boolean): R;
+export declare function useSelect<T extends Record<string, DeepstateNode<unknown>>, R>(nodes: T, selector: (values: {
+    [K in keyof T]: T[K] extends DeepstateNode<infer V> ? V : never;
+}) => R, equalityFn?: (a: R, b: R) => boolean): R;
 /**
  * @deprecated Use `useSelect` instead. This is an alias for backwards compatibility.
  */
@@ -133,5 +136,79 @@ export declare const useStateValue: typeof useSelect;
  * @deprecated Use `useSelect` instead. This is an alias for backwards compatibility.
  */
 export declare const useSelector: typeof useSelect;
+/**
+ * Hook to subscribe to a piped observable stream.
+ * Unlike `useSelect`, this hook is designed for observables that have been transformed
+ * with RxJS operators like `filter`, `debounceTime`, `map`, etc.
+ *
+ * Since piped observables don't have a synchronous `.get()` method, the initial value
+ * is `undefined` until the first emission occurs.
+ *
+ * @param piped$ - An RxJS Observable (typically created by calling .pipe() on a deepstate node)
+ * @returns The current value from the stream, or `undefined` if no value has been emitted yet
+ *
+ * @example Basic usage with filter
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { filter } from 'rxjs';
+ *
+ * function OnlyPositive() {
+ *   // Will be undefined until a value > 0 is emitted
+ *   const value = usePipeSelect(store.count.pipe(filter(v => v > 0)));
+ *
+ *   if (value === undefined) {
+ *     return <span>Waiting for positive value...</span>;
+ *   }
+ *   return <span>{value}</span>;
+ * }
+ * ```
+ *
+ * @example Debouncing high-frequency updates
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { debounceTime } from 'rxjs';
+ *
+ * function DebouncedInput() {
+ *   // Reduces re-renders by debouncing updates
+ *   const searchTerm = usePipeSelect(store.searchInput.pipe(debounceTime(300)));
+ *
+ *   return <span>Searching for: {searchTerm ?? 'nothing yet'}</span>;
+ * }
+ * ```
+ *
+ * @example Mapping values
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { map } from 'rxjs';
+ *
+ * function ItemCount() {
+ *   const count = usePipeSelect(store.items.pipe(map(items => items.length)));
+ *
+ *   return <span>Count: {count ?? 0}</span>;
+ * }
+ * ```
+ *
+ * @example Combining operators
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { filter, debounceTime, distinctUntilChanged } from 'rxjs';
+ *
+ * function FilteredSearch() {
+ *   const results = usePipeSelect(
+ *     store.searchResults.pipe(
+ *       filter(r => r.length > 0),
+ *       debounceTime(200),
+ *       distinctUntilChanged()
+ *     )
+ *   );
+ *
+ *   if (results === undefined) {
+ *     return <span>No results yet</span>;
+ *   }
+ *   return <ul>{results.map(r => <li key={r.id}>{r.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export declare function usePipeSelect<T>(piped$: Observable<T>): T | undefined;
 export {};
 //# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

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

package/dist/index.d.ts

@@ -32,6 +32,7 @@
  * }
  * ```
  */
-export { useSelect, useObservable, useStateValue, useSelector, } from "./hooks";
+export { useSelect, usePipeSelect, useObservable, useStateValue, useSelector, } from "./hooks";
+export type { DeepstateNode } from "./hooks";
 export type { Observable } from "rxjs";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -104,9 +104,24 @@ function useSelect(nodeOrNodes, selector, equalityFn = Object.is) {
 }
 var useStateValue = useSelect;
 var useSelector = useSelect;
+function usePipeSelect(piped$) {
+  const hasValueRef = useRef(false);
+  const valueRef = useRef(undefined);
+  const subscribe = useCallback((onStoreChange) => {
+    const subscription = piped$.subscribe((newValue) => {
+      hasValueRef.current = true;
+      valueRef.current = newValue;
+      onStoreChange();
+    });
+    return () => subscription.unsubscribe();
+  }, [piped$]);
+  const getSnapshot = useCallback(() => valueRef.current, []);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
 export {
   useStateValue,
   useSelector,
   useSelect,
+  usePipeSelect,
   useObservable
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@montra-interactive/deepstate-react",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "React bindings for deepstate - Proxy-based reactive state management with RxJS.",
   "keywords": [
     "react",

package/src/hooks.ts

@@ -31,6 +31,12 @@ interface NodeWithGet<T> {
   get(): T;
 }
 
+/**
+ * A deepstate node - an Observable that also has a synchronous get() method.
+ * Used to enforce that useSelect only accepts deepstate nodes, not piped observables.
+ */
+export type DeepstateNode<T> = Observable<T> & NodeWithGet<T>;
+
 function hasGet<T>(obj: unknown): obj is NodeWithGet<T> {
   if (obj === null || typeof obj !== "object") return false;
   // Check by accessing get directly - works with proxied observables
@@ -184,65 +190,45 @@ export function useObservable<T>(
  * ```
  */
 // Single node, no selector - return raw value
-export function useSelect<T extends Observable<unknown>>(
-  node: T
-): ObservableValue<T>;
+// Note: Requires a deepstate node (with .get()), not a piped observable.
+// Use usePipeSelect for piped observables.
+export function useSelect<T>(
+  node: DeepstateNode<T>
+): T;
 // Single node with selector
-export function useSelect<T extends Observable<unknown>, R>(
-  node: T,
-  selector: (value: ObservableValue<T>) => R,
+export function useSelect<T, R>(
+  node: DeepstateNode<T>,
+  selector: (value: T) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Array of 2 nodes with selector
-export function useSelect<
-  T1 extends Observable<unknown>,
-  T2 extends Observable<unknown>,
-  R
->(
-  nodes: [T1, T2],
-  selector: (values: [ObservableValue<T1>, ObservableValue<T2>]) => R,
+export function useSelect<T1, T2, R>(
+  nodes: [DeepstateNode<T1>, DeepstateNode<T2>],
+  selector: (values: [T1, T2]) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Array of 3 nodes with selector
-export function useSelect<
-  T1 extends Observable<unknown>,
-  T2 extends Observable<unknown>,
-  T3 extends Observable<unknown>,
-  R
->(
-  nodes: [T1, T2, T3],
-  selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>]) => R,
+export function useSelect<T1, T2, T3, R>(
+  nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>],
+  selector: (values: [T1, T2, T3]) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Array of 4 nodes with selector
-export function useSelect<
-  T1 extends Observable<unknown>,
-  T2 extends Observable<unknown>,
-  T3 extends Observable<unknown>,
-  T4 extends Observable<unknown>,
-  R
->(
-  nodes: [T1, T2, T3, T4],
-  selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>, ObservableValue<T4>]) => R,
+export function useSelect<T1, T2, T3, T4, R>(
+  nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>, DeepstateNode<T4>],
+  selector: (values: [T1, T2, T3, T4]) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Array of 5 nodes with selector
-export function useSelect<
-  T1 extends Observable<unknown>,
-  T2 extends Observable<unknown>,
-  T3 extends Observable<unknown>,
-  T4 extends Observable<unknown>,
-  T5 extends Observable<unknown>,
-  R
->(
-  nodes: [T1, T2, T3, T4, T5],
-  selector: (values: [ObservableValue<T1>, ObservableValue<T2>, ObservableValue<T3>, ObservableValue<T4>, ObservableValue<T5>]) => R,
+export function useSelect<T1, T2, T3, T4, T5, R>(
+  nodes: [DeepstateNode<T1>, DeepstateNode<T2>, DeepstateNode<T3>, DeepstateNode<T4>, DeepstateNode<T5>],
+  selector: (values: [T1, T2, T3, T4, T5]) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Object of nodes with selector
-export function useSelect<T extends Record<string, Observable<unknown>>, R>(
+export function useSelect<T extends Record<string, DeepstateNode<unknown>>, R>(
   nodes: T,
-  selector: (values: ObservableObjectValues<T>) => R,
+  selector: (values: { [K in keyof T]: T[K] extends DeepstateNode<infer V> ? V : never }) => R,
   equalityFn?: (a: R, b: R) => boolean
 ): R;
 // Implementation
@@ -364,3 +350,99 @@ export const useStateValue = useSelect;
  * @deprecated Use `useSelect` instead. This is an alias for backwards compatibility.
  */
 export const useSelector = useSelect;
+
+/**
+ * Hook to subscribe to a piped observable stream.
+ * Unlike `useSelect`, this hook is designed for observables that have been transformed
+ * with RxJS operators like `filter`, `debounceTime`, `map`, etc.
+ * 
+ * Since piped observables don't have a synchronous `.get()` method, the initial value
+ * is `undefined` until the first emission occurs.
+ * 
+ * @param piped$ - An RxJS Observable (typically created by calling .pipe() on a deepstate node)
+ * @returns The current value from the stream, or `undefined` if no value has been emitted yet
+ * 
+ * @example Basic usage with filter
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { filter } from 'rxjs';
+ * 
+ * function OnlyPositive() {
+ *   // Will be undefined until a value > 0 is emitted
+ *   const value = usePipeSelect(store.count.pipe(filter(v => v > 0)));
+ *   
+ *   if (value === undefined) {
+ *     return <span>Waiting for positive value...</span>;
+ *   }
+ *   return <span>{value}</span>;
+ * }
+ * ```
+ * 
+ * @example Debouncing high-frequency updates
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { debounceTime } from 'rxjs';
+ * 
+ * function DebouncedInput() {
+ *   // Reduces re-renders by debouncing updates
+ *   const searchTerm = usePipeSelect(store.searchInput.pipe(debounceTime(300)));
+ *   
+ *   return <span>Searching for: {searchTerm ?? 'nothing yet'}</span>;
+ * }
+ * ```
+ * 
+ * @example Mapping values
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { map } from 'rxjs';
+ * 
+ * function ItemCount() {
+ *   const count = usePipeSelect(store.items.pipe(map(items => items.length)));
+ *   
+ *   return <span>Count: {count ?? 0}</span>;
+ * }
+ * ```
+ * 
+ * @example Combining operators
+ * ```tsx
+ * import { usePipeSelect } from '@montra-interactive/deepstate-react';
+ * import { filter, debounceTime, distinctUntilChanged } from 'rxjs';
+ * 
+ * function FilteredSearch() {
+ *   const results = usePipeSelect(
+ *     store.searchResults.pipe(
+ *       filter(r => r.length > 0),
+ *       debounceTime(200),
+ *       distinctUntilChanged()
+ *     )
+ *   );
+ *   
+ *   if (results === undefined) {
+ *     return <span>No results yet</span>;
+ *   }
+ *   return <ul>{results.map(r => <li key={r.id}>{r.name}</li>)}</ul>;
+ * }
+ * ```
+ */
+export function usePipeSelect<T>(piped$: Observable<T>): T | undefined {
+  // Track whether we've received a value yet
+  const hasValueRef = useRef(false);
+  const valueRef = useRef<T | undefined>(undefined);
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const subscription = piped$.subscribe((newValue) => {
+        hasValueRef.current = true;
+        valueRef.current = newValue;
+        onStoreChange();
+      });
+
+      return () => subscription.unsubscribe();
+    },
+    [piped$]
+  );
+
+  const getSnapshot = useCallback(() => valueRef.current, []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/index.ts

@@ -35,10 +35,13 @@
 
 export {
   useSelect,
+  usePipeSelect,
   useObservable,
   // Deprecated aliases for backwards compatibility
   useStateValue,
   useSelector,
 } from "./hooks";
 
+export type { DeepstateNode } from "./hooks";
+
 export type { Observable } from "rxjs";