@zuzjs/flare 0.2.21 → 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
@@ -593,6 +776,10 @@ const uploaded = await storage.putObject({
   },
 });
 
+console.log(uploaded.key);    // users/alice.png
+console.log(uploaded.access); // public (default)
+console.log(uploaded.url);    // https://.../storage/public/<appId>/avatars/users%2Falice.png
+
 // ── Base64 upload (opt-in, small files only) ─────────────────────────────────
 // Pass `base64: true` to use the legacy base64-over-JSON path.
 // If the payload exceeds `base64MaxBytes` (default 4 MiB), the SDK
@@ -602,6 +789,7 @@ const uploaded2 = await storage.putObject({
   key: 'users/thumb.png',
   body: smallFileBytes,
   contentType: 'image/png',
+  access: 'private',   // override the default public access
   base64: true,         // prefer base64 path
   base64MaxBytes: 2 * 1024 * 1024, // cap at 2 MiB; larger → raw upload
 });
@@ -612,12 +800,17 @@ const uploaded3 = await storage.putObject({
   key: 'users/icon.png',
   contentBase64: alreadyEncodedString,
   contentType: 'image/png',
+  // encrypt defaults to false when omitted
 });
 
 const head = await storage.headObject({ bucket: 'avatars', key: uploaded.key });
+console.log(head.access, head.url);
+
 const file = await storage.getObject({ bucket: 'avatars', key: uploaded.key });
 
 const page1 = await storage.listObjects({ bucket: 'avatars', prefix: 'users/', limit: 100 });
+console.log(page1.objects[0]?.access, page1.objects[0]?.url);
+
 const page2 = page1.cursor
   ? await storage.listObjects({ bucket: 'avatars', prefix: 'users/', limit: 100, cursor: page1.cursor })
   : { objects: [] };
@@ -640,6 +833,7 @@ const signedUpload = await storage.createSignedUrl({
   action: FlareStorageSignedAction.Upload,
   expiresInSeconds: 300,
   contentType: 'video/mp4',
+  access: 'private',
   encrypt: true,
 });
 
@@ -723,6 +917,9 @@ const embedUrl = await storage.getObjectUrl({
 ```
 
 Notes:
+- `putObject()` defaults to `encrypt: false` and `access: 'public'`.
+- `uploaded.url` is the stable public object URL shape. Anonymous reads still depend on stored `access` and any storage rules configured on the app.
+- `headObject()` and `listObjects()` also return `access` and `url` metadata.
 - `forceDownload` and `embedOnly` are mutually exclusive.
 - `allowedOrigins` defaults to `['*']` when omitted.
 - `embedOnly` is valid only for download signed URLs.

package/dist/grpc.d.cts

@@ -1,4 +1,4 @@
-import { F as FlareConfig, aR as StructuredQuery } from './index-DlQgWDy-.cjs';
+import { F as FlareConfig, aR as StructuredQuery } from './index-18tMqAtM.cjs';
 import '@zuzjs/auth';
 
 declare function runGrpcQuery<T = Record<string, unknown>>(config: FlareConfig, collection: string, query: StructuredQuery): Promise<T[] | null>;

package/dist/grpc.d.ts

@@ -1,4 +1,4 @@
-import { F as FlareConfig, aR as StructuredQuery } from './index-DlQgWDy-.js';
+import { F as FlareConfig, aR as StructuredQuery } from './index-18tMqAtM.js';
 import '@zuzjs/auth';
 
 declare function runGrpcQuery<T = Record<string, unknown>>(config: FlareConfig, collection: string, query: StructuredQuery): Promise<T[] | null>;

package/dist/{index-DlQgWDy-.d.cts → index-18tMqAtM.d.cts}

@@ -264,6 +264,8 @@ interface FlareStorageObjectResult {
     ok: boolean;
     path: string;
     key: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted?: boolean;
     size?: number;
     contentBase64?: string;
@@ -282,6 +284,7 @@ interface FlareStorageSignedUrlInput {
     expiresInSeconds?: number;
     sizeBytes?: number;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
     decrypt?: boolean;
     forceDownload?: boolean;
@@ -370,6 +373,8 @@ interface StorageObjectMeta {
     bucket: string;
     size: number;
     contentType: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted: boolean;
     createdAt?: unknown;
     updatedAt?: unknown;
@@ -402,7 +407,9 @@ interface PutObjectInput {
      */
     base64MaxBytes?: number;
     contentType?: string;
-    /** Encrypt at rest with AES-256-GCM. Defaults to true. */
+    /** Public/private object access. Defaults to public. */
+    access?: "public" | "private";
+    /** Encrypt at rest with AES-256-GCM. Defaults to false. */
     encrypt?: boolean;
     /** Upload progress callback. Only fires in browser environments. */
     onProgress?: (progress: StorageProgress) => void;
@@ -411,6 +418,8 @@ interface PutObjectResult {
     ok: boolean;
     bucket: string;
     key: string;
+    access: "public" | "private";
+    url?: string;
     size: number;
     encrypted: boolean;
 }
@@ -503,6 +512,7 @@ interface StorageSignedUrlInput {
     expiresInSeconds?: number;
     sizeBytes?: number;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
     decrypt?: boolean;
     forceDownload?: boolean;

package/dist/{index-DlQgWDy-.d.ts → index-18tMqAtM.d.ts}

@@ -264,6 +264,8 @@ interface FlareStorageObjectResult {
     ok: boolean;
     path: string;
     key: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted?: boolean;
     size?: number;
     contentBase64?: string;
@@ -282,6 +284,7 @@ interface FlareStorageSignedUrlInput {
     expiresInSeconds?: number;
     sizeBytes?: number;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
     decrypt?: boolean;
     forceDownload?: boolean;
@@ -370,6 +373,8 @@ interface StorageObjectMeta {
     bucket: string;
     size: number;
     contentType: string;
+    access?: "public" | "private";
+    url?: string;
     encrypted: boolean;
     createdAt?: unknown;
     updatedAt?: unknown;
@@ -402,7 +407,9 @@ interface PutObjectInput {
      */
     base64MaxBytes?: number;
     contentType?: string;
-    /** Encrypt at rest with AES-256-GCM. Defaults to true. */
+    /** Public/private object access. Defaults to public. */
+    access?: "public" | "private";
+    /** Encrypt at rest with AES-256-GCM. Defaults to false. */
     encrypt?: boolean;
     /** Upload progress callback. Only fires in browser environments. */
     onProgress?: (progress: StorageProgress) => void;
@@ -411,6 +418,8 @@ interface PutObjectResult {
     ok: boolean;
     bucket: string;
     key: string;
+    access: "public" | "private";
+    url?: string;
     size: number;
     encrypted: boolean;
 }
@@ -503,6 +512,7 @@ interface StorageSignedUrlInput {
     expiresInSeconds?: number;
     sizeBytes?: number;
     contentType?: string;
+    access?: "public" | "private";
     encrypt?: boolean;
     decrypt?: boolean;
     forceDownload?: boolean;

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

@@ -1,4 +1,4 @@
-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-DlQgWDy-.js';
+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';
 
 /**

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

@@ -1,4 +1,4 @@
-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-DlQgWDy-.cjs';
+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';
 
 /**