@zuzjs/flare 0.2.22 → 0.2.24

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

package/dist/{index-CRByt4Qw.d.ts → index-CXCOH5iN.d.ts}

@@ -1,5 +1,5 @@
 import { b0 as WhereCondition, aT as SubscriptionCallback, aw as QueryConfig, J as DocUpdatedCallback, I as DocDeletedCallback, H as DocChangedCallback, ay as QueryPresetMap, az as QueryPresetParams, aA as QueryPresetRow, a as AggregateSpec, ae as HavingClause, ah as JoinClause, a_ as VectorSearchClause, aR as StructuredQuery, aX as SubscriptionHandle, u as CollectionStreamOptions, r as CollectionStream, q as CollectionExternalStore, G as DocAddedCallback, m as BulkWriteOptions, o as BulkWriteResult, aY as UpdateManyItem, F as FlareConfig, aS as SubscribeOptions, aW as SubscriptionErrorCallback, aV as SubscriptionError, v as ConnectionState, ap as PresenceCallback, aq as PresenceJoinCallback, ar as PresenceLeaveCallback, aZ as VectorFieldConfig, aB as QueryPresetSpec, a8 as FlareStorageTransferManagerConfig, aN as StorageProgress, aL as StorageBucketInput, aK as StorageBucket, k as BucketPolicyInput, a1 as FlareStorageRulesPolicy, j as BucketCorsRule, a0 as FlareStorageRulesHistoryResult, au as PutObjectInput, av as PutObjectResult, aa as GetObjectInput, ab as GetObjectResult, ac as GetObjectUrlInput, L as DownloadObjectInput, M as DownloadObjectResult, af as HeadObjectInput, aM as StorageObjectMeta, ag as HeadObjectsInput, aj as ListObjectsInput, ak as ListObjectsResult, w as CopyObjectInput, z as DeleteObjectInput, E as DeleteObjectsInput, aO as StorageSignedUrlInput, a7 as FlareStorageSignedUrlResult, P as FlareAuthConfig, f as AuthStateListener, d as AuthConfigListener, U as FlareAuthSession, V as FlareAuthUser, Q as FlareAuthHydrationInput, R as FlareAuthHydrationOptions, i as BrowserPushTokenOptions, B as BrowserPushRegistrationOptions, aD as RegisterPushTokenInput, aI as SendPushNotificationInput, at as PushSendResult, e as AuthResult } from './index-18tMqAtM.js';
-import { AuthToken } from '@zuzjs/auth';
+import { AuthGuard, AuthToken, ProviderId } from '@zuzjs/auth';
 
 /**
  * Parse ORM-style where condition: { age: ">= 25", role: "admin" }
@@ -729,6 +729,7 @@ declare class FlareAuth<TPresetMap extends QueryPresetMap = {}> extends FlareBas
     protected authBootstrapAttempted: boolean;
     protected authBootstrapPromise?: Promise<void>;
     protected socketAuthSyncPromise?: Promise<void>;
+    protected authGuard?: AuthGuard;
     /** In-memory CSRF token extracted from the `x-flare-csrf` response header */
     protected csrfToken?: string;
     protected csrfBootstrapAttempted: boolean;
@@ -1064,6 +1065,40 @@ declare class FlareAuth<TPresetMap extends QueryPresetMap = {}> extends FlareBas
         email: string;
         sessionsRevoked?: number;
     }>;
+    signIn(providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signIn(authGuard: Pick<AuthGuard, 'signIn'>, providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGoogle(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGitHub(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithFacebook(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithDropbox(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    handleSignInRedirect(autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    handleSignInRedirect(authGuard: Pick<AuthGuard, 'handleRedirect'>, autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    private exchangeProviderToken;
+    protected getAuthGuard(): Promise<AuthGuard>;
     signOut(): Promise<void>;
     protected registerWithEmail(email: string, password: string, options?: {
         scope?: string[];

package/dist/{index-DOaU2Hxo.d.cts → index-D53u7tRA.d.cts}

@@ -1,5 +1,5 @@
 import { b0 as WhereCondition, aT as SubscriptionCallback, aw as QueryConfig, J as DocUpdatedCallback, I as DocDeletedCallback, H as DocChangedCallback, ay as QueryPresetMap, az as QueryPresetParams, aA as QueryPresetRow, a as AggregateSpec, ae as HavingClause, ah as JoinClause, a_ as VectorSearchClause, aR as StructuredQuery, aX as SubscriptionHandle, u as CollectionStreamOptions, r as CollectionStream, q as CollectionExternalStore, G as DocAddedCallback, m as BulkWriteOptions, o as BulkWriteResult, aY as UpdateManyItem, F as FlareConfig, aS as SubscribeOptions, aW as SubscriptionErrorCallback, aV as SubscriptionError, v as ConnectionState, ap as PresenceCallback, aq as PresenceJoinCallback, ar as PresenceLeaveCallback, aZ as VectorFieldConfig, aB as QueryPresetSpec, a8 as FlareStorageTransferManagerConfig, aN as StorageProgress, aL as StorageBucketInput, aK as StorageBucket, k as BucketPolicyInput, a1 as FlareStorageRulesPolicy, j as BucketCorsRule, a0 as FlareStorageRulesHistoryResult, au as PutObjectInput, av as PutObjectResult, aa as GetObjectInput, ab as GetObjectResult, ac as GetObjectUrlInput, L as DownloadObjectInput, M as DownloadObjectResult, af as HeadObjectInput, aM as StorageObjectMeta, ag as HeadObjectsInput, aj as ListObjectsInput, ak as ListObjectsResult, w as CopyObjectInput, z as DeleteObjectInput, E as DeleteObjectsInput, aO as StorageSignedUrlInput, a7 as FlareStorageSignedUrlResult, P as FlareAuthConfig, f as AuthStateListener, d as AuthConfigListener, U as FlareAuthSession, V as FlareAuthUser, Q as FlareAuthHydrationInput, R as FlareAuthHydrationOptions, i as BrowserPushTokenOptions, B as BrowserPushRegistrationOptions, aD as RegisterPushTokenInput, aI as SendPushNotificationInput, at as PushSendResult, e as AuthResult } from './index-18tMqAtM.cjs';
-import { AuthToken } from '@zuzjs/auth';
+import { AuthGuard, AuthToken, ProviderId } from '@zuzjs/auth';
 
 /**
  * Parse ORM-style where condition: { age: ">= 25", role: "admin" }
@@ -729,6 +729,7 @@ declare class FlareAuth<TPresetMap extends QueryPresetMap = {}> extends FlareBas
     protected authBootstrapAttempted: boolean;
     protected authBootstrapPromise?: Promise<void>;
     protected socketAuthSyncPromise?: Promise<void>;
+    protected authGuard?: AuthGuard;
     /** In-memory CSRF token extracted from the `x-flare-csrf` response header */
     protected csrfToken?: string;
     protected csrfBootstrapAttempted: boolean;
@@ -1064,6 +1065,40 @@ declare class FlareAuth<TPresetMap extends QueryPresetMap = {}> extends FlareBas
         email: string;
         sessionsRevoked?: number;
     }>;
+    signIn(providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signIn(authGuard: Pick<AuthGuard, 'signIn'>, providerId: ProviderId, options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGoogle(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithGitHub(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithFacebook(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    signInWithDropbox(options?: {
+        returnTo?: string;
+        metaTag?: string;
+    }): Promise<any>;
+    handleSignInRedirect(autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    handleSignInRedirect(authGuard: Pick<AuthGuard, 'handleRedirect'>, autoRedirect?: boolean): Promise<(AuthResult & {
+        authToken: AuthToken;
+        provider?: ProviderId;
+    }) | null>;
+    private exchangeProviderToken;
+    protected getAuthGuard(): Promise<AuthGuard>;
     signOut(): Promise<void>;
     protected registerWithEmail(email: string, password: string, options?: {
         scope?: string[];