@woodleighschool/bloby-client 0.2.0 → 1.0.0

package/README.md

@@ -1,3 +1,20 @@
 # @woodleighschool/bloby-client
 
-Headless browser transfers for [Bloby](../../bloby). The server chooses direct or multipart ingestion; this package transfers the bytes and returns the completed parts. Applications retain resource creation, finalization, attachment, progress UI and request integration.
+Headless browser transfers for [Bloby](../../bloby). The server chooses direct or multipart ingestion. `upload` resolves after the complete transfer is accepted by storage; applications own publication, attachment and UI.
+
+```ts
+await upload({
+  strategy: "multipart",
+  blob: file,
+  signal,
+  onProgress,
+  multipart: {
+    signPart: (partNumber, signal) => signPartRequest(partNumber, signal),
+    complete: (parts, signal) => completeMultipartRequest(parts, signal),
+  },
+});
+```
+
+The callbacks adapt application endpoints. Multipart completion must be idempotent: the client retries a failed completion once without retransmitting the parts. Part transfers also retry once with a fresh signed target. Cancellation preserves the supplied `AbortSignal` reason and stops further signing, transfers and completion retries. Finalization or attachment of the resulting object is a separate application operation.
+
+For a direct upload, pass the server's `{ strategy: "direct-put", target }` action together with the blob and options. The core package has no React, router or API-client dependency.

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export interface UploadTarget {
 }
 export interface MultipartUploadRequest {
     signPart: (partNumber: number, signal?: AbortSignal) => Promise<UploadTarget>;
+    complete: (parts: CompletedPart[], signal?: AbortSignal) => Promise<void>;
 }
 export type UploadAction = {
     strategy: "direct-put";
@@ -27,17 +28,9 @@ export interface CompletedPart {
     part_number: number;
     etag: string;
 }
-export type UploadResult = {
-    strategy: "direct-put";
-} | {
-    strategy: "multipart";
-    parts: CompletedPart[];
-};
-type UploadContext = {
+export interface UploadOptions {
     blob: Blob;
     signal?: AbortSignal;
     onProgress?: (progress: UploadProgress) => void;
-};
-export type UploadExecution = UploadRequest & UploadContext;
-export declare function upload(request: UploadExecution): Promise<UploadResult>;
-export {};
+}
+export declare function upload(request: UploadRequest & UploadOptions): Promise<void>;

package/dist/index.js

@@ -2,16 +2,20 @@
 // multipart upload to 10,000 parts.
 const multipartPartSize = 64 * 1024 * 1024;
 const maximumMultipartParts = 10_000;
+// Resolves after storage accepts the complete upload. Publishing and attaching
+// the object remain application operations.
 export async function upload(request) {
     if (request.strategy === "direct-put") {
         await uploadTarget(request.target, request.blob, request.blob.size, 0, request.onProgress, request.signal);
-        return { strategy: "direct-put" };
+        return;
     }
     return uploadWithMultipartProgress(request);
 }
 async function uploadWithMultipartProgress(request) {
     const { blob, signal, onProgress } = request;
-    throwIfCancelled(signal);
+    signal?.throwIfAborted();
+    if (blob.size === 0)
+        throw new Error("Multipart uploads require a nonempty blob.");
     const partSize = Math.max(multipartPartSize, Math.ceil(blob.size / maximumMultipartParts));
     const parts = [];
     let completedBytes = 0;
@@ -22,14 +26,27 @@ async function uploadWithMultipartProgress(request) {
         completedBytes += chunk.size;
         onProgress?.(uploadProgress(completedBytes, blob.size));
     }
-    return { strategy: "multipart", parts };
+    // Completion is idempotent: a lost response must not require transferring
+    // the parts again. Only the storage completion callback is retried.
+    for (let attempt = 0;; attempt++) {
+        signal?.throwIfAborted();
+        try {
+            await request.multipart.complete(parts, signal);
+            return;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (attempt === 1)
+                throw error;
+        }
+    }
 }
 async function uploadPart(multipart, partNumber, chunk, totalBytes, completedBytes, onProgress, signal) {
     let lastError;
     for (let attempt = 0; attempt < 2; attempt++) {
-        throwIfCancelled(signal);
-        const target = await multipart.signPart(partNumber, signal);
+        signal?.throwIfAborted();
         try {
+            const target = await multipart.signPart(partNumber, signal);
             const etag = await uploadTarget(target, chunk, totalBytes, completedBytes, onProgress, signal);
             if (!etag) {
                 throw new Error(`Multipart part ${partNumber} did not return an ETag.`);
@@ -37,8 +54,7 @@ async function uploadPart(multipart, partNumber, chunk, totalBytes, completedByt
             return etag;
         }
         catch (error) {
-            if (signal?.aborted)
-                throw cancelledError();
+            signal?.throwIfAborted();
             lastError = error;
             onProgress?.(uploadProgress(completedBytes, totalBytes));
         }
@@ -48,7 +64,7 @@ async function uploadPart(multipart, partNumber, chunk, totalBytes, completedByt
 function uploadTarget(target, body, totalBytes, completedBytes, onProgress, signal) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
-            reject(cancelledError());
+            reject(signal.reason);
             return;
         }
         const xhr = new XMLHttpRequest();
@@ -71,14 +87,20 @@ function uploadTarget(target, body, totalBytes, completedBytes, onProgress, sign
         });
         xhr.addEventListener("abort", () => {
             finish();
-            reject(cancelledError());
+            reject(signal?.reason ?? new DOMException("Upload aborted", "AbortError"));
         });
         signal?.addEventListener("abort", abort, { once: true });
-        xhr.open(target.method, target.url);
-        for (const [key, value] of Object.entries(target.headers ?? {})) {
-            xhr.setRequestHeader(key, value);
+        try {
+            xhr.open(target.method, target.url);
+            for (const [key, value] of Object.entries(target.headers ?? {})) {
+                xhr.setRequestHeader(key, value);
+            }
+            xhr.send(body);
+        }
+        catch (error) {
+            finish();
+            reject(error);
         }
-        xhr.send(body);
     });
 }
 function uploadProgress(loaded, total) {
@@ -88,10 +110,3 @@ function uploadProgress(loaded, total) {
         percent: total > 0 ? Math.round((loaded / total) * 100) : 0,
     };
 }
-function throwIfCancelled(signal) {
-    if (signal?.aborted)
-        throw cancelledError();
-}
-function cancelledError() {
-    return new Error("Upload cancelled.");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@woodleighschool/bloby-client",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Headless browser transfers for Bloby direct and multipart uploads.",
   "homepage": "https://github.com/woodleighschool/goodies/tree/main/packages/bloby-client",
   "bugs": "https://github.com/woodleighschool/goodies/issues",