@livequery/react 2.0.136 → 2.0.137

package/README.md

@@ -193,6 +193,98 @@ Behavior notes:
 - If the source is `undefined`, the hook returns the default value, or `undefined` if no default was provided.
 - Reading `.value` or `.getValue()` manually in render is not a replacement for `useObservable()` because it will not subscribe the component to future emissions.
 
+## Rendering a Collection (Mandatory Pattern)
+
+`collection.items` is a `BehaviorSubject<BehaviorSubject<T>[]>`. This two-level structure is intentional and must be respected to achieve both realtime updates and high render performance.
+
+**How it works:**
+
+- The outer `BehaviorSubject` emits a new array only when items are added, removed, or reordered.
+- Each element in the array is itself a `BehaviorSubject<T>` that emits whenever that specific item's fields change.
+- A field update on one item emits only that item's inner subject — the outer array does not change and the parent list does not re-render.
+
+This means correct rendering requires three separate component layers:
+
+### Rule 1 — Subscribe to the items array in the parent
+
+```tsx
+const items = useObservable(collection.items, [])
+// items = BehaviorSubject<T>[]
+// Re-renders only when item count or order changes
+```
+
+### Rule 2 — Render each item in its own component
+
+Pass the `BehaviorSubject<T>` as a prop and call `useObservable` inside the child. Field changes re-render only that child.
+
+```tsx
+function TodoItem({ item$ }: { item$: BehaviorSubject<Todo> }) {
+  const item = useObservable(item$)
+  return <li>{item.title}</li>
+}
+```
+
+### Rule 3 — Render loading state in its own component
+
+`collection.loading` is also a `BehaviorSubject<boolean>`. Place it in a separate component so toggling loading does not re-render the item list.
+
+```tsx
+function TodoLoading({ loading$ }: { loading$: BehaviorSubject<boolean> }) {
+  const loading = useObservable(loading$)
+  if (!loading) return null
+  return <p>Loading...</p>
+}
+```
+
+### Full example
+
+```tsx
+import { useEffect } from 'react'
+import { BehaviorSubject } from 'rxjs'
+import { useCollection, useObservable } from '@livequery/react'
+
+type Todo = { _id: string; title: string; done: boolean }
+
+function TodoLoading({ loading$ }: { loading$: BehaviorSubject<boolean> }) {
+  const loading = useObservable(loading$)
+  if (!loading) return null
+  return <p>Loading...</p>
+}
+
+function TodoItem({ item$ }: { item$: BehaviorSubject<Todo> }) {
+  const item = useObservable(item$)
+  return <li>{item.title}</li>
+}
+
+export function TodoList() {
+  const collection = useCollection<Todo>('todos')
+  const items = useObservable(collection.items, [])
+
+  useEffect(() => {
+    collection.query()
+  }, [collection])
+
+  return (
+    <>
+      <TodoLoading loading$={collection.loading} />
+      <ul>
+        {items.map((item$) => (
+          <TodoItem key={item$.getValue()._id} item$={item$} />
+        ))}
+      </ul>
+    </>
+  )
+}
+```
+
+**Why this matters:**
+
+- Putting `useObservable(collection.loading)` and `useObservable(collection.items)` in the same parent component means every loading toggle re-renders the entire list, even when nothing changed.
+- Calling `useObservable(item$)` inside the parent map instead of a child component means every field change on any single item re-renders the whole list.
+- Following all three rules gives true per-item granularity: only the component that owns a changed field re-renders.
+
+> **Never** flatten `collection.items` by calling `useObservable` on each element inside the parent map. Always delegate to a child component.
+
 ## `useAction`
 
 `useAction(fn, options)` wraps an async function and attaches action state to the returned callable.
@@ -283,6 +375,9 @@ Behavior notes:
 - Passing changing `useCollection()` options and expecting the existing collection instance to rebuild.
 - Using `useDocument()` when you need error state or collection methods.
 - Importing APIs not listed in the `Exports` section.
+- Calling `useObservable(item$)` for each item inside the parent `.map()` instead of delegating to a child component — this causes the entire list to re-render on every field change of any single item.
+- Observing `collection.loading` in the same component as the item list — loading state changes then re-render the full list.
+- Treating `collection.items` as a plain array — it is a `BehaviorSubject<BehaviorSubject<T>[]>` and must be observed at both levels to get correct realtime behavior.
 
 ## Build
 

package/dist/useObservable.d.ts

@@ -1,6 +1,7 @@
 import { Observable, BehaviorSubject } from "rxjs";
 export type MaybeFunction<T> = T | (() => T);
-type ObservableSource<T> = MaybeFunction<BehaviorSubject<T> | Observable<T>> | undefined;
+type Source<T> = BehaviorSubject<T> | Observable<T>;
+type ObservableSource<T> = MaybeFunction<Source<T>> | undefined;
 export declare function useObservable<T>(o: BehaviorSubject<T>): T;
 export declare function useObservable<T>(o: ObservableSource<T>): T | undefined;
 export declare function useObservable<T>(o: ObservableSource<T>, default_value: T): T;

package/dist/useObservable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useObservable.d.ts","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAc,MAAM,MAAM,CAAC;AAG/D,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5C,KAAK,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAExF,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAC1D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;AACvE,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"useObservable.d.ts","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAO,MAAM,MAAM,CAAC;AAGxD,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AAE5C,KAAK,MAAM,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;AACnD,KAAK,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAU/D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AAC1D,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAA;AACvE,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,GAAG,CAAC,CAAA"}

package/dist/useObservable.js

@@ -1,22 +1,28 @@
 import { useEffect, useRef, useState } from "react";
-import { Observable, BehaviorSubject, tap, EMPTY } from "rxjs";
+import { Observable, BehaviorSubject, tap } from "rxjs";
 import { skip } from "rxjs/operators";
+const isBehaviorSubject = (source) => {
+    return typeof source?.getValue === 'function';
+};
+const hasPipe = (source) => {
+    return typeof source?.pipe === 'function';
+};
 export function useObservable(o, default_value) {
-    const prev = useRef(o);
-    const source = o || EMPTY;
-    const isBehaviorSubject = typeof o == 'object' && typeof source.getValue === 'function';
-    const dfv = isBehaviorSubject ? source.getValue() : default_value;
-    const [v, s] = useState(dfv);
+    const lazySource = useRef(undefined);
+    const source = typeof o === 'function'
+        ? lazySource.current ?? (lazySource.current = o())
+        : o;
+    const prev = useRef(source);
+    const [v, s] = useState(() => isBehaviorSubject(source) ? source.getValue() : default_value);
     useEffect(() => {
-        const diff = prev.current !== o;
-        prev.current = o;
-        try {
-            const subscription = source.pipe(skip(isBehaviorSubject && !diff ? 1 : 0), tap(s)).subscribe();
-            return () => {
-                subscription.unsubscribe();
-            };
-        }
-        catch (e) { }
+        const diff = prev.current !== source;
+        prev.current = source;
+        if (!hasPipe(source))
+            return;
+        const subscription = source.pipe(skip(isBehaviorSubject(source) && !diff ? 1 : 0), tap(s)).subscribe();
+        return () => {
+            subscription.unsubscribe();
+        };
     }, typeof o === 'function' ? [] : [o]);
     return v;
 }

package/dist/useObservable.js.map

@@ -1 +1 @@
-{"version":3,"file":"useObservable.js","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAUtC,MAAM,UAAU,aAAa,CAAI,CAAmB,EAAE,aAAiB;IACnE,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;IACtB,MAAM,MAAM,GAAG,CAA8B,IAAI,KAAK,CAAA;IACtD,MAAM,iBAAiB,GAAE,OAAO,CAAC,IAAI,QAAQ,IAAK,OAAO,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAA;IACvF,MAAM,GAAG,GAAG,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,aAAa,CAAA;IACjE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAgB,GAAG,CAAC,CAAA;IAC3C,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,KAAK,CAAC,CAAA;QAC/B,IAAI,CAAC,OAAO,GAAG,CAAC,CAAA;QAChB,IAAI,CAAC;YACD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAC5B,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACxC,GAAG,CAAC,CAAC,CAAC,CACT,CAAC,SAAS,EAAE,CAAA;YACb,OAAO,GAAG,EAAE;gBACR,YAAY,CAAC,WAAW,EAAE,CAAA;YAC9B,CAAC,CAAA;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACnB,CAAC,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtC,OAAO,CAAC,CAAA;AACZ,CAAC"}
+{"version":3,"file":"useObservable.js","sourceRoot":"","sources":["../src/useObservable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAOtC,MAAM,iBAAiB,GAAG,CAAI,MAA6B,EAAgC,EAAE;IACzF,OAAO,OAAQ,MAAkD,EAAE,QAAQ,KAAK,UAAU,CAAA;AAC9F,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CAAI,MAA6B,EAAuB,EAAE;IACtE,OAAO,OAAQ,MAA6C,EAAE,IAAI,KAAK,UAAU,CAAA;AACrF,CAAC,CAAA;AAMD,MAAM,UAAU,aAAa,CAAI,CAAsB,EAAE,aAAiB;IACtE,MAAM,UAAU,GAAG,MAAM,CAAwB,SAAS,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,UAAU;QAClC,CAAC,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAClD,CAAC,CAAC,CAAC,CAAA;IACP,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;IAC3B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAgB,GAAG,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAA;IAE3G,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,KAAK,MAAM,CAAA;QACpC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QAErB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAM;QAE5B,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAC5B,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAChD,GAAG,CAAC,CAAC,CAAC,CACT,CAAC,SAAS,EAAE,CAAA;QACb,OAAO,GAAG,EAAE;YACR,YAAY,CAAC,WAAW,EAAE,CAAA;QAC9B,CAAC,CAAA;IACL,CAAC,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEtC,OAAO,CAAC,CAAA;AACZ,CAAC"}

package/package.json

@@ -4,7 +4,7 @@
     "url": "https://github.com/livequery/react"
   },
   "type": "module",
-  "version": "2.0.136",
+  "version": "2.0.137",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",