@zuzjs/flare 0.2.6 → 0.2.8

package/README.md

@@ -158,6 +158,198 @@ await app.sendPushNotification({
 await app.unregisterPushToken(token);
 ```
 
+### Burst Stream API (Chat, Group Chat, Activity Feeds)
+
+Use `stream()` to keep a live in-memory list with batched updates.
+This avoids one render per incoming change during message bursts.
+
+```ts
+const messageStream = app
+  .collection('messages')
+  .where({ roomId: 'room-1' })
+  .latest()
+  .limit(200)
+  .stream({
+    flushMs: 24,        // collapse burst updates into short windows
+    maxBatchSize: 200,  // force flush when queue gets large
+    insertAt: 'start',  // keep latest-first lists stable for chat UIs
+    maxDocs: 200,
+  });
+
+const stop = messageStream.subscribe((rows, meta) => {
+  console.log('rows', rows.length, 'ready', meta.ready, 'reason', meta.reason);
+});
+
+// Read current snapshot any time (works well with external-store patterns)
+const currentRows = messageStream.getSnapshot();
+
+// Optional subscription-level error hooks
+messageStream
+  .onError((err) => console.error('stream error', err))
+  .onPermissionDenied((err) => console.error('permission denied', err));
+
+// Cleanup
+stop();
+messageStream.close();
+```
+
+#### React.js Example
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import { connectApp } from '@zuzjs/flare';
+
+type Message = {
+  id: string;
+  roomId: string;
+  text: string;
+  createdAt: number;
+};
+
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+export function RoomMessages({ roomId }: { roomId: string }) {
+  const [rows, setRows] = useState<readonly Message[]>([]);
+  const [ready, setReady] = useState(false);
+
+  const stream = useMemo(() => {
+    return app
+      .collection<Message>('messages')
+      .where({ roomId })
+      .latest()
+      .limit(200)
+      .stream({ flushMs: 20, maxBatchSize: 250, insertAt: 'start', maxDocs: 200 });
+  }, [roomId]);
+
+  useEffect(() => {
+    const stop = stream.subscribe((nextRows, meta) => {
+      setRows(nextRows);
+      setReady(meta.ready);
+    });
+
+    return () => {
+      stop();
+      stream.close();
+    };
+  }, [stream]);
+
+  if (!ready) return <p>Loading messages...</p>;
+
+  return (
+    <ul>
+      {rows.map((m) => (
+        <li key={m.id}>{m.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### Next.js Example (Client Component)
+
+```tsx
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { connectApp } from '@zuzjs/flare';
+
+type Message = { id: string; roomId: string; text: string; createdAt: number };
+
+const app = connectApp({
+  endpoint: process.env.NEXT_PUBLIC_FLARE_ENDPOINT!,
+  appId: process.env.NEXT_PUBLIC_FLARE_APP_ID!,
+  apiKey: process.env.NEXT_PUBLIC_FLARE_API_KEY,
+});
+
+export default function RoomStream({ roomId }: { roomId: string }) {
+  const store = app
+    .collection<Message>('messages')
+    .where({ roomId })
+    .latest()
+    .limit(200)
+    .asStore({ flushMs: 20, maxBatchSize: 250, insertAt: 'start', maxDocs: 200 });
+
+  const rows = useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getServerSnapshot,
+  );
+
+  return (
+    <section>
+      {rows.map((m) => (
+        <p key={m.id}>{m.text}</p>
+      ))}
+    </section>
+  );
+}
+```
+
+#### Redux Example
+
+```ts
+import { createSlice, PayloadAction, configureStore } from '@reduxjs/toolkit';
+import { connectApp } from '@zuzjs/flare';
+
+type Message = { id: string; roomId: string; text: string; createdAt: number };
+
+const app = connectApp({ endpoint: 'https://flare.zuzcdn.net', appId: 'my-app', apiKey: 'ak' });
+
+const messagesSlice = createSlice({
+  name: 'messages',
+  initialState: [] as Message[],
+  reducers: {
+    replaceMessages: (_state, action: PayloadAction<readonly Message[]>) => [...action.payload],
+  },
+});
+
+export const { replaceMessages } = messagesSlice.actions;
+export const store = configureStore({ reducer: { messages: messagesSlice.reducer } });
+
+export function startRoomMessageStream(roomId: string): () => void {
+  const stream = app
+    .collection<Message>('messages')
+    .where({ roomId })
+    .latest()
+    .limit(200)
+    .stream({ flushMs: 20, maxBatchSize: 250, insertAt: 'start', maxDocs: 200 });
+
+  const stop = stream.subscribe((rows) => {
+    store.dispatch(replaceMessages(rows));
+  });
+
+  return () => {
+    stop();
+    stream.close();
+  };
+}
+```
+
+### External Store Bridge (No Framework Dependency)
+
+The client also exposes `asStore()` so app code can plug into external-store hooks
+while keeping this package free of framework dependencies.
+
+```ts
+const messageStore = app
+  .collection('messages')
+  .where({ roomId: 'room-1' })
+  .latest()
+  .limit(200)
+  .asStore({ flushMs: 24, maxBatchSize: 200, insertAt: 'start' });
+
+// In app code, pass these to your UI store hook:
+messageStore.subscribe;      // (onStoreChange) => unsubscribe
+messageStore.getSnapshot;    // () => readonly rows
+messageStore.getServerSnapshot; // () => []
+
+// Optional advanced access
+messageStore.stream.onError((err) => console.error(err));
+
+// Cleanup
+messageStore.destroy();
+```
+
 ### Direct Query Helpers (Knex-Style)
 
 `collection()` query chaining uses object-based logical steps and dedicated operator families:
@@ -203,6 +395,73 @@ const boardAccess = await app
   .get();
 ```
 
+### Advanced Joins And Relations
+
+Use `join()` when you want direct field mapping, including array/object-path sources.
+
+```ts
+const boardWithLists = await app
+  .collection('boards')
+  .where({ id: boardId, uid: me.uid })
+  .join('lists', {
+    source: 'id',
+    target: 'boardId',
+    as: 'lists',
+  })
+  .limit(1)
+  .get();
+
+const boardWithTeamMembers = await app
+  .collection('boards')
+  .where({ id: boardId, uid: me.uid })
+  .join('users', {
+    source: 'team.uid', // team: [{ uid, role }]
+    target: 'id',
+    as: 'teamMembers',
+  })
+  .limit(1)
+  .get();
+```
+
+Use `withRelation()` for SQL-style shorthand.
+
+```ts
+const boardWithTeamMembers = await app
+  .collection('boards')
+  .where({ id: boardId, uid: me.uid })
+  .withRelation('team.uid->users.id', { as: 'teamMembers' })
+  .limit(1)
+  .get();
+
+const boardWithInlineAlias = await app
+  .collection('boards')
+  .where({ id: boardId, uid: me.uid })
+  .withRelation('team.uid->users.id as teamMembers')
+  .limit(1)
+  .get();
+
+const boardWithMultipleJoins = await app
+  .collection('boards')
+  .where({ id: boardId, uid: me.uid })
+  .join('lists', { source: 'id', target: 'boardId', as: 'lists' })
+  .join('users', { source: 'team.uid', target: 'id', as: 'teamMembers' })
+  .limit(1)
+  .get();
+
+const boardWithNestedJoinChain = await app
+  .collection('boards')
+  .join('lists', { source: 'id', target: 'boardId', as: 'lists' })
+  .joinNested('lists', 'cards', { source: 'id', target: 'listId', as: 'cards' })
+  .joinNested('cards', 'comments', { source: 'id', target: 'cardId', as: 'comments' })
+  .get();
+```
+
+Nested join options are supported per relation (`where`, `orderBy`, `limit`, `offset`, `select`, and nested `joins`).
+
+Join alias note:
+- `.join('users', ...)` and `.join('_users', ...)` both resolve to the app auth-users collection (`_flare_auth_users`) on server.
+- Use `_users` when you want an explicit auth-collection relation in query code.
+
 ### Template-Based Email APIs
 
 ### Security Rules Example (Boards Owner Or Team Member)