@zuzjs/flare 0.2.22 → 0.2.23

package/README.md

@@ -238,6 +238,189 @@ stop();
 messageStream.close();
 ```
 
+### Pagination Patterns (Stream vs Manual)
+
+Use one of these based on UX needs:
+
+- Stream page window: realtime for the current page; rebuild stream when page changes.
+- Manual cursor paging: deterministic `load more` and stable history.
+- Hybrid: stream first page (latest data) and fetch older pages manually.
+
+#### 1) Stream Page Window (offset-based)
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import { collection, Collections, useLiveQuery } from '@zuzjs/flare';
+
+const PAGE_SIZE = 25;
+
+export function ContactsPagedStream() {
+  const [rows, setRows] = useState<any[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [page, setPage] = useState(0);
+
+  const contacts = useLiveQuery({
+    onData: (data, meta) => {
+      setLoading(!meta.ready);
+      setRows(data as any[]);
+    },
+  });
+
+  const query = useMemo(() => {
+    return collection(Collections.Contacts)
+      .where({ sheet: '!= null' })
+      .orderBy('_seq', 'desc')
+      .limit(PAGE_SIZE)
+      .offset(page * PAGE_SIZE);
+  }, [page]);
+
+  useEffect(() => {
+    contacts.buildStream(query);
+    return () => contacts.closeStream();
+  }, [contacts, query]);
+
+  return (
+    <div>
+      <div>{loading ? 'Loading...' : `Rows: ${rows.length}`}</div>
+      <button onClick={() => setPage((p) => Math.max(0, p - 1))}>Prev</button>
+      <button onClick={() => setPage((p) => p + 1)}>Next</button>
+    </div>
+  );
+}
+```
+
+Notes:
+
+- This keeps only one live page at a time.
+- Realtime inserts can shift offset pages; this is expected for live data.
+
+#### 2) Manual Cursor Pagination (recommended for stable "load more")
+
+```tsx
+import { useEffect, useState } from 'react';
+import { collection, Collections } from '@zuzjs/flare';
+
+const PAGE_SIZE = 25;
+
+export function ContactsManualPagination() {
+  const [rows, setRows] = useState<any[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [cursor, setCursor] = useState<number | null>(null);
+  const [hasMore, setHasMore] = useState(true);
+
+  const loadInitial = async () => {
+    setLoading(true);
+    const page = await collection(Collections.Contacts)
+      .where({ sheet: '!= null' })
+      .orderBy('_seq', 'desc')
+      .limit(PAGE_SIZE)
+      .get();
+
+    setRows(page as any[]);
+    const last = (page as any[])[(page as any[]).length - 1];
+    setCursor(last?._seq ?? null);
+    setHasMore((page as any[]).length === PAGE_SIZE);
+    setLoading(false);
+  };
+
+  const loadMore = async () => {
+    if (!hasMore || cursor == null) return;
+    setLoading(true);
+
+    const page = await collection(Collections.Contacts)
+      .where({ sheet: '!= null' })
+      .orderBy('_seq', 'desc')
+      .startAfter(cursor)
+      .limit(PAGE_SIZE)
+      .get();
+
+    const next = page as any[];
+    setRows((prev) => [...prev, ...next]);
+    const last = next[next.length - 1];
+    setCursor(last?._seq ?? null);
+    setHasMore(next.length === PAGE_SIZE);
+    setLoading(false);
+  };
+
+  useEffect(() => {
+    void loadInitial();
+  }, []);
+
+  return (
+    <div>
+      <div>{loading ? 'Loading...' : `Rows: ${rows.length}`}</div>
+      <button onClick={loadMore} disabled={!hasMore || loading}>
+        {hasMore ? 'Load more' : 'No more'}
+      </button>
+    </div>
+  );
+}
+```
+
+#### 3) Hybrid (stream latest page + manual history)
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import { collection, Collections, useLiveQuery } from '@zuzjs/flare';
+
+const PAGE_SIZE = 25;
+
+export function ContactsHybridPagination() {
+  const [liveRows, setLiveRows] = useState<any[]>([]);
+  const [historyRows, setHistoryRows] = useState<any[]>([]);
+  const [historyCursor, setHistoryCursor] = useState<number | null>(null);
+  const [ready, setReady] = useState(false);
+
+  const live = useLiveQuery({
+    onData: (data, meta) => {
+      setReady(meta.ready);
+      setLiveRows(data as any[]);
+    },
+  });
+
+  const liveQuery = useMemo(() => {
+    return collection(Collections.Contacts)
+      .where({ sheet: '!= null' })
+      .orderBy('_seq', 'desc')
+      .limit(PAGE_SIZE);
+  }, []);
+
+  useEffect(() => {
+    live.buildStream(liveQuery);
+    return () => live.closeStream();
+  }, [live, liveQuery]);
+
+  const loadOlder = async () => {
+    const anchor = historyCursor ?? liveRows[liveRows.length - 1]?._seq;
+    if (anchor == null) return;
+
+    const page = await collection(Collections.Contacts)
+      .where({ sheet: '!= null' })
+      .orderBy('_seq', 'desc')
+      .startAfter(anchor)
+      .limit(PAGE_SIZE)
+      .get();
+
+    const next = page as any[];
+    setHistoryRows((prev) => [...prev, ...next]);
+    setHistoryCursor(next[next.length - 1]?._seq ?? anchor);
+  };
+
+  const allRows = [...liveRows, ...historyRows];
+
+  return (
+    <div>
+      <div>{ready ? `Rows: ${allRows.length}` : 'Loading live page...'}</div>
+      <button onClick={loadOlder}>Load older</button>
+    </div>
+  );
+}
+```
+
+Tip:
+
+- For feeds/chat, hybrid mode usually gives the best UX: live top of list + stable older history.
+
 #### React.js Example
 
 ```tsx