@zuzjs/flare 0.2.5 → 0.2.7

package/README.md

@@ -158,8 +158,279 @@ 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:
+
+- Logic: `where({...})`, `and({...})`, `or({...})`
+- `in` family: `in`, `andIn`, `orIn`
+- `notIn` family: `notIn`, `andNotIn`, `orNotIn`
+- `arrayContains` family: `arrayContains`, `andArrayContains`, `orArrayContains`
+- `arrayContainsAny` family: `arrayContainsAny`, `andArrayContainsAny`, `orArrayContainsAny`
+- `some` family (array of objects): `some`, `andSome`, `orSome`
+- `like` family: `like`, `andLike`, `orLike`
+- `notLike` family: `notLike`, `andNotLike`, `orNotLike`
+- `exists` family: `exists`, `andExists`, `orExists`
+- `notExists` family: `notExists`, `andNotExists`, `orNotExists`
+
+```ts
+const uid = 'bDEgnSqsEDT5qdDdtOX1';
+
+const boards = await app
+  .collection('boards')
+  .where({ uid })
+  .orArrayContains('team', uid)
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .get();
+
+const sameBoards = await app
+  .collection('boards')
+  .where({ uid })
+  .orArrayContains('team', uid)
+  .get();
+
+const active = await app
+  .collection('tasks')
+  .in('status', ['todo', 'doing'])
+  .andArrayContainsAny('labels', ['urgent', 'backend'])
+  .andLike('title', '%bug%')
+  .get();
+
+const boardAccess = await app
+  .collection('boards')
+  .some('team', { uid: 'xyz', role: 1 })
+  .get();
+```
+
 ### Template-Based Email APIs
 
+### Security Rules Example (Boards Owner Or Team Member)
+
+For a `boards` document shape like:
+
+```json
+{
+  "uid": "ownerUid",
+  "team": ["memberUid1", "memberUid2"]
+}
+```
+
+Use this DSL to allow read for owner or team member, and allow write only for owner:
+
+```txt
+service cloud.firestore {
+  match /databases/{database}/documents {
+    function isOwner(ownerUid) {
+      return auth != null && auth.uid == ownerUid;
+    }
+
+    function isTeamMember(teamUids) {
+      return auth != null && auth.uid in teamUids;
+    }
+
+    match /boards/{boardId} {
+      allow read: if isOwner(resourceData.uid) || isTeamMember(resourceData.team);
+      allow create, update, delete: if isOwner(resourceData.uid);
+    }
+  }
+}
+```
+
+Tip: if you set owner uid at create time, prefer checking `requestData.uid` on create and `resourceData.uid` on update/delete.
+
 Emails are sent only through app-level templates stored in `_flare_email_templates`.
 
 Template placeholders use `{key}` syntax and are replaced from `values`.