@zuzjs/flare 0.2.26 → 0.2.28

package/README.md

@@ -473,6 +473,98 @@ export function RoomMessages({ roomId }: { roomId: string }) {
 }
 ```
 
+#### React Storage Queue Hook (Start/Pause)
+
+```tsx
+import { useMemo } from 'react';
+import { connectApp } from '@zuzjs/flare';
+import { useStorage, Status } from '@zuzjs/flare/react';
+
+const app = connectApp({
+  endpoint: 'http://localhost:8080',
+  appId: 'my-app',
+});
+
+export function StorageUploader() {
+  const storage = useMemo(() => app.storage(), []);
+
+  const upload = useStorage(storage, {
+    onItemComplete: (item, result) => {
+      console.log('uploaded', item.objectKey, result.url);
+    },
+    onItemError: (item, err) => {
+      console.error('upload failed', item.objectKey, err.message);
+    },
+  });
+
+  const onSelect = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(event.target.files ?? []);
+    if (!files.length) return;
+
+    upload.addToQueue(
+      files.map((file) => ({
+        file,
+        bucket: 'attachments',
+        key: `uploads/${Date.now()}-${file.name}`,
+        contentType: file.type || 'application/octet-stream',
+        access: 'public',
+      })),
+    );
+  };
+
+  return (
+    <div>
+      <input type='file' multiple onChange={onSelect} />
+
+      <div style={{ display: 'flex', gap: 8, marginTop: 12 }}>
+        <button onClick={() => void upload.start()} disabled={!upload.hasPending || upload.running}>
+          Start
+        </button>
+        <button onClick={upload.pause} disabled={!upload.running}>
+          Pause
+        </button>
+      </div>
+
+      <ul>
+        {upload.que.map((item) => (
+          <li key={item.id}>
+            {item.objectKey} - {item.progress}% - {Status[item.status]}
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+`addToQueue(...)` auto-starts uploads by default.
+
+Manual mode example (only upload when `start()` is clicked):
+
+```tsx
+const upload = useStorage(storage, {
+  autoStartOnAdd: false,
+});
+
+upload.addToQueue([
+  {
+    file,
+    bucket: 'attachments',
+    key: `uploads/${Date.now()}-${file.name}`,
+  },
+]);
+
+await upload.start();
+```
+
+Notes:
+
+- Queue items expose `item.objectKey` (not `item.key`) to avoid React prop-name conflicts.
+- `addToQueue(...)` input still uses `key` because it maps directly to `putObject({ key })`.
+- `addToQueue(...)` starts processing immediately unless `autoStartOnAdd: false` or the queue is paused.
+- `pause()` stops scheduling new uploads; it does not cancel an already in-flight request.
+- Call `start()` again to continue with remaining queued items.
+
 #### Next.js Example (Client Component)
 
 ```tsx

package/dist/{index-CnmBBd-u.d.cts → index-BDbL-6Rr.d.cts}

@@ -490,8 +490,8 @@ declare class FlareBase<TPresetMap extends QueryPresetMap = {}> {
     onError(callback: ErrorListener): () => void;
     collection<T = any>(name: string): CollectionQuery<T, TPresetMap>;
     /**
-     * Generates a standard 20-character Flare document ID.
-     * UUID v4 without dashes, first 20 chars — matches the Rust server-side format.
+     * Generates a 24-character hex document ID (Mongo ObjectId compatible format).
+     * UUID v4 without dashes, first 24 chars.
      *
      * ```ts
      * const id = db.generateFlareId();

package/dist/{index-DPlKzY-d.d.ts → index-DvHbnHDV.d.ts}

@@ -490,8 +490,8 @@ declare class FlareBase<TPresetMap extends QueryPresetMap = {}> {
     onError(callback: ErrorListener): () => void;
     collection<T = any>(name: string): CollectionQuery<T, TPresetMap>;
     /**
-     * Generates a standard 20-character Flare document ID.
-     * UUID v4 without dashes, first 20 chars — matches the Rust server-side format.
+     * Generates a 24-character hex document ID (Mongo ObjectId compatible format).
+     * UUID v4 without dashes, first 24 chars.
      *
      * ```ts
      * const id = db.generateFlareId();