@trustgraph/react-state 1.5.2 → 1.5.3

package/dist/index.cjs

@@ -4642,6 +4642,552 @@ const useNodeDetails = (nodeId, flowId) => {
     };
 };
 
+// Default chunk size: 5MB (matches backend default)
+const DEFAULT_CHUNK_SIZE$1 = 5 * 1024 * 1024;
+// Maximum parallel chunk uploads
+const DEFAULT_PARALLEL_UPLOADS = 3;
+/**
+ * Hook for managing chunked document uploads with progress tracking
+ *
+ * Features:
+ * - Automatic chunking of large files
+ * - Parallel chunk uploads for performance
+ * - Progress tracking (bytes, percentage, chunks)
+ * - Pause/resume support
+ * - Cancel support
+ * - Resumability after interruption
+ *
+ * @param options - Configuration options for the upload
+ * @returns Upload state and control methods
+ */
+const useChunkedUpload = (options = {}) => {
+    const { chunkSize = DEFAULT_CHUNK_SIZE$1, parallelUploads = DEFAULT_PARALLEL_UPLOADS, onProgress, onComplete, onError, } = options;
+    const socket = reactProvider.useSocket();
+    const connectionState = reactProvider.useConnectionState();
+    const queryClient = reactQuery.useQueryClient();
+    const notify = useNotification();
+    // Upload state
+    const [progress, setProgress] = react.useState({
+        totalBytes: 0,
+        bytesUploaded: 0,
+        percentage: 0,
+        totalChunks: 0,
+        chunksUploaded: 0,
+        pendingChunks: [],
+        status: "idle",
+    });
+    // Refs for managing upload lifecycle
+    const abortControllerRef = react.useRef(null);
+    const isPausedRef = react.useRef(false);
+    const currentFileRef = react.useRef(null);
+    const uploadIdRef = react.useRef(null);
+    // Update progress and notify callback
+    const updateProgress = react.useCallback((updates) => {
+        setProgress((prev) => {
+            const next = { ...prev, ...updates };
+            onProgress?.(next);
+            return next;
+        });
+    }, [onProgress]);
+    // Read a chunk from the file as base64
+    const readChunkAsBase64 = react.useCallback(async (file, chunkIndex, chunkSz) => {
+        const start = chunkIndex * chunkSz;
+        const end = Math.min(start + chunkSz, file.size);
+        const blob = file.slice(start, end);
+        return new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => {
+                const dataUrl = reader.result;
+                // Extract base64 from data URL
+                const base64 = dataUrl.replace(/^data:[^;]+;base64,/, "");
+                resolve(base64);
+            };
+            reader.onerror = () => reject(new Error("Failed to read file chunk"));
+            reader.readAsDataURL(blob);
+        });
+    }, []);
+    // Upload chunks in parallel with concurrency limit
+    const uploadChunks = react.useCallback(async (file, uploadId, pendingChunks, chunkSz, totalChunks) => {
+        const remaining = [...pendingChunks];
+        let completedCount = totalChunks - remaining.length;
+        let bytesUploaded = completedCount * chunkSz;
+        // Process chunks with limited parallelism
+        const uploadNextBatch = async () => {
+            while (remaining.length > 0 && !abortControllerRef.current?.signal.aborted) {
+                // Wait if paused
+                if (isPausedRef.current) {
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                    continue;
+                }
+                // Take up to parallelUploads chunks
+                const batch = remaining.splice(0, parallelUploads);
+                // Upload batch in parallel
+                const results = await Promise.allSettled(batch.map(async (chunkIndex) => {
+                    const content = await readChunkAsBase64(file, chunkIndex, chunkSz);
+                    await socket.librarian().uploadChunk(uploadId, chunkIndex, content);
+                    return chunkIndex;
+                }));
+                // Process results
+                for (const result of results) {
+                    if (result.status === "fulfilled") {
+                        completedCount++;
+                        // Calculate actual bytes for this chunk
+                        const chunkIdx = result.value;
+                        const chunkStart = chunkIdx * chunkSz;
+                        const chunkEnd = Math.min(chunkStart + chunkSz, file.size);
+                        bytesUploaded += chunkEnd - chunkStart;
+                        updateProgress({
+                            chunksUploaded: completedCount,
+                            bytesUploaded,
+                            percentage: Math.round((bytesUploaded / file.size) * 100),
+                            pendingChunks: [...remaining],
+                        });
+                    }
+                    else {
+                        // Re-add failed chunk to retry
+                        const failedIndex = batch[results.indexOf(result)];
+                        remaining.push(failedIndex);
+                        console.warn(`Chunk ${failedIndex} failed, will retry:`, result.reason);
+                    }
+                }
+            }
+        };
+        await uploadNextBatch();
+    }, [socket, parallelUploads, readChunkAsBase64, updateProgress]);
+    /**
+     * Start a new chunked upload
+     */
+    const upload = react.useCallback(async (params) => {
+        const { file, title, comments = "", tags = [], collection, documentId } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return null;
+        }
+        // Reset state
+        abortControllerRef.current = new AbortController();
+        isPausedRef.current = false;
+        currentFileRef.current = file;
+        const docId = documentId || createDocId();
+        const totalChunks = Math.ceil(file.size / chunkSize);
+        const pendingChunks = Array.from({ length: totalChunks }, (_, i) => i);
+        updateProgress({
+            totalBytes: file.size,
+            bytesUploaded: 0,
+            percentage: 0,
+            totalChunks,
+            chunksUploaded: 0,
+            pendingChunks,
+            status: "preparing",
+            error: undefined,
+            uploadId: undefined,
+            documentId: undefined,
+        });
+        try {
+            // Initialize upload session
+            const metadata = {
+                id: docId,
+                time: Math.floor(Date.now() / 1000),
+                kind: file.type || "application/octet-stream",
+                title,
+                comments,
+                user: "trustgraph", // Will be set by server based on auth
+                collection: collection || "default",
+                tags,
+            };
+            const beginResponse = await socket
+                .librarian()
+                .beginUpload(metadata, file.size, chunkSize);
+            const uploadId = beginResponse["upload-id"];
+            uploadIdRef.current = uploadId;
+            updateProgress({
+                status: "uploading",
+                uploadId,
+            });
+            // Upload all chunks
+            await uploadChunks(file, uploadId, pendingChunks, chunkSize, totalChunks);
+            // Check if cancelled
+            if (abortControllerRef.current?.signal.aborted) {
+                return null;
+            }
+            // Complete the upload
+            updateProgress({ status: "completing" });
+            const completeResponse = await socket.librarian().completeUpload(uploadId);
+            const finalDocId = completeResponse["document-id"];
+            updateProgress({
+                status: "completed",
+                documentId: finalDocId,
+                percentage: 100,
+            });
+            // Invalidate documents cache
+            queryClient.invalidateQueries({ queryKey: ["documents"] });
+            notify.success(`Upload complete: ${title}`);
+            onComplete?.(finalDocId);
+            return finalDocId;
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateProgress({ status: "error", error: errorMsg });
+            notify.error(`Upload failed: ${errorMsg}`);
+            onError?.(errorMsg);
+            return null;
+        }
+    }, [
+        socket,
+        connectionState,
+        chunkSize,
+        queryClient,
+        notify,
+        updateProgress,
+        uploadChunks,
+        onComplete,
+        onError,
+    ]);
+    /**
+     * Resume an interrupted upload
+     */
+    const resume = react.useCallback(async (params) => {
+        const { uploadId, file } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return null;
+        }
+        abortControllerRef.current = new AbortController();
+        isPausedRef.current = false;
+        currentFileRef.current = file;
+        uploadIdRef.current = uploadId;
+        updateProgress({
+            status: "preparing",
+            uploadId,
+        });
+        try {
+            // Get current upload status
+            const status = await socket.librarian().getUploadStatus(uploadId);
+            if (status["upload-state"] === "completed") {
+                updateProgress({ status: "completed" });
+                return null;
+            }
+            if (status["upload-state"] === "expired") {
+                throw new Error("Upload session has expired");
+            }
+            const totalChunks = status["total-chunks"];
+            const missingChunks = status["missing-chunks"];
+            const bytesReceived = status["bytes-received"];
+            const totalBytes = status["total-bytes"];
+            updateProgress({
+                totalBytes,
+                bytesUploaded: bytesReceived,
+                percentage: Math.round((bytesReceived / totalBytes) * 100),
+                totalChunks,
+                chunksUploaded: totalChunks - missingChunks.length,
+                pendingChunks: missingChunks,
+                status: "uploading",
+            });
+            // Upload missing chunks
+            const effectiveChunkSize = status["chunk-size"] || chunkSize;
+            await uploadChunks(file, uploadId, missingChunks, effectiveChunkSize, totalChunks);
+            // Check if cancelled
+            if (abortControllerRef.current?.signal.aborted) {
+                return null;
+            }
+            // Complete the upload
+            updateProgress({ status: "completing" });
+            const completeResponse = await socket.librarian().completeUpload(uploadId);
+            const finalDocId = completeResponse["document-id"];
+            updateProgress({
+                status: "completed",
+                documentId: finalDocId,
+                percentage: 100,
+            });
+            // Invalidate documents cache
+            queryClient.invalidateQueries({ queryKey: ["documents"] });
+            notify.success("Upload resumed and completed");
+            onComplete?.(finalDocId);
+            return finalDocId;
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateProgress({ status: "error", error: errorMsg });
+            notify.error(`Resume failed: ${errorMsg}`);
+            onError?.(errorMsg);
+            return null;
+        }
+    }, [
+        socket,
+        connectionState,
+        chunkSize,
+        queryClient,
+        notify,
+        updateProgress,
+        uploadChunks,
+        onComplete,
+        onError,
+    ]);
+    /**
+     * Pause the current upload
+     */
+    const pause = react.useCallback(() => {
+        if (progress.status === "uploading") {
+            isPausedRef.current = true;
+            updateProgress({ status: "paused" });
+        }
+    }, [progress.status, updateProgress]);
+    /**
+     * Resume a paused upload (not to be confused with resuming an interrupted upload)
+     */
+    const unpause = react.useCallback(() => {
+        if (progress.status === "paused") {
+            isPausedRef.current = false;
+            updateProgress({ status: "uploading" });
+        }
+    }, [progress.status, updateProgress]);
+    /**
+     * Cancel the current upload
+     */
+    const cancel = react.useCallback(async () => {
+        abortControllerRef.current?.abort();
+        if (uploadIdRef.current) {
+            try {
+                await socket.librarian().abortUpload(uploadIdRef.current);
+            }
+            catch (err) {
+                console.warn("Failed to abort upload on server:", err);
+            }
+        }
+        updateProgress({
+            status: "cancelled",
+            pendingChunks: [],
+        });
+        uploadIdRef.current = null;
+        currentFileRef.current = null;
+    }, [socket, updateProgress]);
+    /**
+     * Reset the upload state to idle
+     */
+    const reset = react.useCallback(() => {
+        abortControllerRef.current?.abort();
+        uploadIdRef.current = null;
+        currentFileRef.current = null;
+        isPausedRef.current = false;
+        setProgress({
+            totalBytes: 0,
+            bytesUploaded: 0,
+            percentage: 0,
+            totalChunks: 0,
+            chunksUploaded: 0,
+            pendingChunks: [],
+            status: "idle",
+        });
+    }, []);
+    return {
+        // Current progress state
+        progress,
+        // Control methods
+        upload,
+        resume,
+        pause,
+        unpause,
+        cancel,
+        reset,
+        // Convenience flags
+        isIdle: progress.status === "idle",
+        isUploading: progress.status === "uploading",
+        isPaused: progress.status === "paused",
+        isCompleted: progress.status === "completed",
+        isError: progress.status === "error",
+    };
+};
+
+// Default chunk size for downloads: 1MB
+const DEFAULT_CHUNK_SIZE = 1024 * 1024;
+/**
+ * Decode base64 string to Uint8Array
+ */
+const base64ToUint8Array = (base64) => {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+};
+/**
+ * Trigger browser download of a Blob
+ */
+const triggerBrowserDownload = (blob, filename) => {
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+};
+/**
+ * Hook for managing streamed document downloads with progress tracking
+ *
+ * Features:
+ * - Streams large documents via WebSocket streaming response
+ * - Progress tracking (chunks received, percentage)
+ * - Cancel support
+ * - Returns Blob or triggers browser download
+ *
+ * @param options - Configuration options for the download
+ * @returns Download state and control methods
+ */
+const useChunkedDownload = (options = {}) => {
+    const { chunkSize = DEFAULT_CHUNK_SIZE, onProgress, onComplete, onError, } = options;
+    const socket = reactProvider.useSocket();
+    const connectionState = reactProvider.useConnectionState();
+    const notify = useNotification();
+    // Download state
+    const [progress, setProgress] = react.useState({
+        totalChunks: 0,
+        chunksReceived: 0,
+        percentage: 0,
+        status: "idle",
+    });
+    // Refs for managing download lifecycle
+    const cancelledRef = react.useRef(false);
+    const chunksRef = react.useRef(new Map());
+    // Update progress and notify callback
+    const updateProgress = react.useCallback((updates) => {
+        setProgress((prev) => {
+            const next = { ...prev, ...updates };
+            onProgress?.(next);
+            return next;
+        });
+    }, [onProgress]);
+    /**
+     * Download a document via streaming and return as Blob
+     */
+    const download = react.useCallback((params) => {
+        const { documentId, mimeType = "application/octet-stream", filename } = params;
+        // Validate connection
+        if (connectionState?.status !== "authenticated" &&
+            connectionState?.status !== "unauthenticated") {
+            const error = "Not connected to server";
+            updateProgress({ status: "error", error });
+            onError?.(error);
+            return Promise.resolve(null);
+        }
+        // Reset state
+        cancelledRef.current = false;
+        chunksRef.current = new Map();
+        updateProgress({
+            totalChunks: 0,
+            chunksReceived: 0,
+            percentage: 0,
+            status: "downloading",
+            error: undefined,
+            documentId,
+        });
+        return new Promise((resolve) => {
+            const onChunk = (content, chunkIndex, totalChunks, complete) => {
+                // Check for cancellation
+                if (cancelledRef.current) {
+                    return;
+                }
+                // Store chunk
+                const chunkData = base64ToUint8Array(content);
+                chunksRef.current.set(chunkIndex, chunkData);
+                const chunksReceived = chunksRef.current.size;
+                const percentage = totalChunks > 0
+                    ? Math.round((chunksReceived / totalChunks) * 100)
+                    : 0;
+                updateProgress({
+                    totalChunks,
+                    chunksReceived,
+                    percentage,
+                });
+                // If complete, reassemble and return
+                if (complete) {
+                    if (cancelledRef.current) {
+                        resolve(null);
+                        return;
+                    }
+                    // Reassemble chunks in order
+                    const orderedChunks = [];
+                    for (let i = 0; i < totalChunks; i++) {
+                        const chunk = chunksRef.current.get(i);
+                        if (chunk) {
+                            orderedChunks.push(chunk);
+                        }
+                    }
+                    const blob = new Blob(orderedChunks, { type: mimeType });
+                    updateProgress({
+                        status: "completed",
+                        percentage: 100,
+                        chunksReceived: totalChunks,
+                    });
+                    // Trigger browser download if filename provided
+                    if (filename) {
+                        triggerBrowserDownload(blob, filename);
+                    }
+                    notify.success("Download complete");
+                    onComplete?.(blob, documentId);
+                    resolve(blob);
+                }
+            };
+            const onStreamError = (error) => {
+                if (cancelledRef.current) {
+                    return;
+                }
+                updateProgress({ status: "error", error });
+                notify.error(`Download failed: ${error}`);
+                onError?.(error);
+                resolve(null);
+            };
+            // Start streaming download
+            socket.librarian().streamDocument(documentId, onChunk, onStreamError, chunkSize);
+        });
+    }, [socket, connectionState, chunkSize, notify, updateProgress, onComplete, onError]);
+    /**
+     * Cancel the current download
+     */
+    const cancel = react.useCallback(() => {
+        cancelledRef.current = true;
+        chunksRef.current = new Map();
+        updateProgress({
+            status: "cancelled",
+        });
+    }, [updateProgress]);
+    /**
+     * Reset the download state to idle
+     */
+    const reset = react.useCallback(() => {
+        cancelledRef.current = true;
+        chunksRef.current = new Map();
+        setProgress({
+            totalChunks: 0,
+            chunksReceived: 0,
+            percentage: 0,
+            status: "idle",
+        });
+    }, []);
+    return {
+        // Current progress state
+        progress,
+        // Control methods
+        download,
+        cancel,
+        reset,
+        // Convenience flags
+        isIdle: progress.status === "idle",
+        isDownloading: progress.status === "downloading",
+        isCompleted: progress.status === "completed",
+        isError: progress.status === "error",
+    };
+};
+
 Object.defineProperty(exports, "ConnectionStateContext", {
     enumerable: true,
     get: function () { return reactProvider.ConnectionStateContext; }
@@ -4669,6 +5215,8 @@ exports.useActivity = useActivity;
 exports.useAgentTools = useAgentTools;
 exports.useChat = useChat;
 exports.useChatSession = useChatSession;
+exports.useChunkedDownload = useChunkedDownload;
+exports.useChunkedUpload = useChunkedUpload;
 exports.useCollections = useCollections;
 exports.useConversation = useConversation;
 exports.useDocumentEmbeddingsQuery = useDocumentEmbeddingsQuery;