Expose the onUploadUrlAvailable callback option (#543)

* Expose the onUploadUrlAvailable callback option

* Implement requested changes

* Update api.md

* Fix linting issues

---------

Co-authored-by: Marius <[email protected]>
Co-authored-by: Marius <[email protected]>

Author: 3 people

docs/api.md

@@ -94,18 +94,24 @@ onShouldRetry: function (err, retryAttempt, options) {
     console.log("Error", err)
     console.log("Request", err.originalRequest)
     console.log("Response", err.originalResponse)
-    
+
     var status = err.originalResponse ? err.originalResponse.getStatus() : 0
     // Do not retry if the status is a 403.
     if (status === 403) {
       return false
     }
-    
+
     // For any other status code, we retry.
     return true
 }
 ```
 
+#### onUploadUrlAvailable
+
+*Default value:* `null`
+
+An optional function called once the upload URL is available. At this point, the `tus.Upload#url` property is guaranteed to be accessible and valid. This occurs after inspecting the `Location` header in the response to the initial POST request, or when an upload URL is confirmed using a HEAD request. Due to network errors and retries, this callback might be invoked multiple times for a single upload.
+
 #### headers
 
 *Default value:* `{}`

lib/index.d.ts

@@ -33,6 +33,7 @@ interface UploadOptions {
   onSuccess?: (() => void) | null;
   onError?: ((error: (Error | DetailedError)) => void) | null;
   onShouldRetry?: ((error: (Error | DetailedError), retryAttempt: number, options: UploadOptions) => boolean) | null;
+  onUploadUrlAvailable?: (() => void) | null;
 
   overridePatchMethod?: boolean;
   headers?: { [key: string]: string };

lib/upload.js

@@ -12,11 +12,11 @@ const defaultOptions = {
   fingerprint: null,
   uploadSize : null,
 
-  onProgress           : null,
-  onChunkComplete      : null,
-  onSuccess            : null,
-  onError              : null,
-  _onUploadUrlAvailable: null,
+  onProgress          : null,
+  onChunkComplete     : null,
+  onSuccess           : null,
+  onError             : null,
+  onUploadUrlAvailable: null,
 
   overridePatchMethod: false,
   headers            : {},
@@ -311,7 +311,7 @@ class BaseUpload {
             },
             // Wait until every partial upload has an upload URL, so we can add
             // them to the URL storage.
-            _onUploadUrlAvailable: () => {
+            onUploadUrlAvailable: () => {
               this._parallelUploadUrls[index] = upload.url
               // Test if all uploads have received an URL
               if (this._parallelUploadUrls.filter(u => Boolean(u)).length === parts.length) {
@@ -568,8 +568,8 @@ class BaseUpload {
       this.url = resolveUrl(this.options.endpoint, location)
       log(`Created upload at ${this.url}`)
 
-      if (typeof this.options._onUploadUrlAvailable === 'function') {
-        this.options._onUploadUrlAvailable()
+      if (typeof this.options.onUploadUrlAvailable === 'function') {
+        this.options.onUploadUrlAvailable()
       }
 
       if (this._size === 0) {
@@ -647,8 +647,8 @@ class BaseUpload {
         return
       }
 
-      if (typeof this.options._onUploadUrlAvailable === 'function') {
-        this.options._onUploadUrlAvailable()
+      if (typeof this.options.onUploadUrlAvailable === 'function') {
+        this.options.onUploadUrlAvailable()
       }
 
       this._saveUploadInUrlStorage()

test/spec/test-common.js

@@ -40,9 +40,10 @@ describe('tus', () => {
           nonlatin: 'słońce',
           number  : 100,
         },
-        withCredentials: true,
+        withCredentials     : true,
         onProgress () {},
-        onSuccess      : waitableFunction(),
+        onUploadUrlAvailable: waitableFunction('onUploadUrlAvailable'),
+        onSuccess           : waitableFunction('onSuccess'),
       }
       spyOn(options, 'onProgress')
 
@@ -68,6 +69,8 @@ describe('tus', () => {
 
       req = await testStack.nextRequest()
 
+      expect(options.onUploadUrlAvailable).toHaveBeenCalled()
+
       expect(req.url).toBe('https://tus.io/uploads/blargh')
       expect(req.method).toBe('PATCH')
       expect(req.requestHeaders.Custom).toBe('blargh')
@@ -533,11 +536,12 @@ describe('tus', () => {
       const testStack = new TestHttpStack()
       const file = getBlob('hello world')
       const options = {
-        httpStack: testStack,
-        endpoint : 'http://tus.io/uploads',
-        uploadUrl: 'http://tus.io/files/upload',
+        httpStack           : testStack,
+        endpoint            : 'http://tus.io/uploads',
+        uploadUrl           : 'http://tus.io/files/upload',
         onProgress () {},
-        onSuccess: waitableFunction('onSuccess'),
+        onUploadUrlAvailable: waitableFunction('onUploadUrlAvailable'),
+        onSuccess           : waitableFunction('onSuccess'),
         fingerprint () {},
       }
       spyOn(options, 'fingerprint').and.resolveTo('fingerprinted')
@@ -562,6 +566,9 @@ describe('tus', () => {
       })
 
       req = await testStack.nextRequest()
+
+      expect(options.onUploadUrlAvailable).toHaveBeenCalled()
+
       expect(req.url).toBe('http://tus.io/files/upload')
       expect(req.method).toBe('PATCH')
       expect(req.requestHeaders['Tus-Resumable']).toBe('1.0.0')