Implement progressiveUrlSaving for parallel uploads

Author: m7kvqbe1

README.md

@@ -55,6 +55,22 @@ input.addEventListener('change', function (e) {
 })
 ```
 
+### Parallel Uploads with Progressive URL Saving
+
+For better fault tolerance with parallel uploads, you can enable progressive URL saving:
+
+```js
+var upload = new tus.Upload(file, {
+  endpoint: 'http://localhost:1080/files/',
+  parallelUploads: 4,
+  progressiveUrlSaving: true, // Save each partial upload URL immediately
+  urlStorage: myThreadSafeStorage, // Your storage implementation
+  // ... other options
+})
+```
+
+When enabled, partial upload URLs are saved immediately as each completes, rather than waiting for all to finish. This improves resumability if failures occur during parallel uploads. See the [API documentation](docs/api.md#progressiveurlsaving) for implementation details.
+
 ## Documentation
 
 - [Installation & Requirements](/docs/installation.md)

docs/api.md

@@ -248,6 +248,47 @@ _Default value:_ `false`
 
 A boolean indicating if the fingerprint in the URL storage will be removed once the upload is successfully completed. When this feature is enabled and the same file is uploaded again, it will create an entirely new upload instead of reusing the previous one. Furthermore, this option will only change behavior if `urlStorage` is not `null`.
 
+#### progressiveUrlSaving
+
+_Default value:_ `false`
+
+A boolean indicating whether partial upload URLs should be saved progressively during parallel uploads. When `false` (default), all partial upload URLs must be successfully created before any are saved to storage. When `true`, each partial upload URL is saved immediately after its POST request succeeds.
+
+This option only has an effect when `parallelUploads` is greater than 1. Enabling this provides better fault tolerance for parallel uploads:
+- If a browser crash or network failure occurs, successfully created partial uploads can still be resumed
+- Earlier persistence reduces the window of data loss
+- More granular progress tracking across sessions
+
+When using this option, your `urlStorage` implementation should handle concurrent updates safely, especially if using a database backend. Consider using a mutex or other synchronization mechanism to prevent race conditions when multiple parallel uploads save their URLs simultaneously.
+
+Example usage with a thread-safe storage implementation:
+```js
+import { Mutex } from 'async-mutex'
+
+class ThreadSafeUrlStorage {
+  constructor() {
+    this.mutex = new Mutex()
+  }
+
+  async addUpload(fingerprint, upload) {
+    const release = await this.mutex.acquire()
+    try {
+      // Merge parallelUploadUrls arrays safely
+      // Your database operations here
+    } finally {
+      release()
+    }
+  }
+}
+
+const upload = new tus.Upload(file, {
+  parallelUploads: 4,
+  progressiveUrlSaving: true,
+  urlStorage: new ThreadSafeUrlStorage(),
+  // ... other options
+})
+```
+
 #### uploadLengthDeferred
 
 _Default value:_ `false`

lib/options.ts

@@ -85,6 +85,7 @@ export interface UploadOptions {
   parallelUploadBoundaries?: { start: number; end: number }[]
   storeFingerprintForResuming: boolean
   removeFingerprintOnSuccess: boolean
+  progressiveUrlSaving: boolean
   uploadLengthDeferred: boolean
   uploadDataDuringCreation: boolean
 

lib/upload.ts

@@ -47,6 +47,7 @@ export const defaultOptions = {
   parallelUploadBoundaries: undefined,
   storeFingerprintForResuming: true,
   removeFingerprintOnSuccess: false,
+  progressiveUrlSaving: false,
   uploadLengthDeferred: false,
   uploadDataDuringCreation: false,
 
@@ -361,10 +362,17 @@ export class BaseUpload {
           onUploadUrlAvailable: async () => {
             // @ts-expect-error We know that _parallelUploadUrls is defined
             this._parallelUploadUrls[index] = upload.url
-            // Test if all uploads have received an URL
-            // @ts-expect-error We know that _parallelUploadUrls is defined
-            if (this._parallelUploadUrls.filter((u) => Boolean(u)).length === parts.length) {
-              await this._saveUploadInUrlStorage()
+
+            // Progressive saving: save immediately when each URL becomes available
+            // This allows for better fault tolerance and earlier persistence
+            if (this.options.progressiveUrlSaving && upload.url) {
+              await this._savePartialUploadUrl(index, upload.url)
+            } else {
+              // Legacy behavior: wait for all URLs before saving
+              // @ts-expect-error We know that _parallelUploadUrls is defined
+              if (this._parallelUploadUrls.filter((u) => Boolean(u)).length === parts.length) {
+                await this._saveUploadInUrlStorage()
+              }
             }
           },
         }
@@ -1010,6 +1018,35 @@ export class BaseUpload {
     this._urlStorageKey = undefined
   }
 
+  /**
+   * Save a single partial upload URL at the specified index.
+   * This is used for progressive URL saving during parallel uploads.
+   *
+   * @api private
+   */
+  private async _savePartialUploadUrl(index: number, url: string): Promise<void> {
+    if (
+      !this.options.storeFingerprintForResuming ||
+      !this._fingerprint
+    ) {
+      return
+    }
+
+    const storedUpload: PreviousUpload = {
+      size: this._size,
+      metadata: this.options.metadata,
+      creationTime: new Date().toString(),
+      urlStorageKey: this._fingerprint,
+      parallelUploadUrls: this._parallelUploadUrls,
+    }
+
+    // Save/update the upload with the current state of parallel URLs,
+    // The UrlStorage implementation must handle concurrent updates
+    // safely when using this method.
+    const urlStorageKey = await this.options.urlStorage.addUpload(this._fingerprint, storedUpload)
+    this._urlStorageKey = urlStorageKey
+  }
+
   /**
    * Add the upload URL to the URL storage, if possible.
    *