feat: add support for .throwOnError() (#250)

maxmetcalfe · web-flow · commit a814b7de5b3f · 2025-09-08T11:51:54.000+03:00
diff --git a/README.md b/README.md
@@ -156,6 +156,21 @@ const storageClient = new StorageClient(STORAGE_URL, {
   const { data, error } = await storageClient.from('public-bucket').getPublicUrl('path/to/file')
   ```
 
+### Error Handling
+
+Supplying `.throwOnError()` will throw errors instead of returning them as a property on the response object.
+
+  ```js
+  try {
+    const { data } = await storageClient
+      .from('bucket')
+      .throwOnError()
+      .download('path/to/file')
+  } catch (error) {
+    console.error(error)
+  }
+  ```
+
 ## Sponsors
 
 We are building the features of Firebase using enterprise-grade, open source products. We support existing communities wherever possible, and if the products don’t exist we build them and open source them ourselves. Thanks to these sponsors who are making the OSS ecosystem better for everyone.
diff --git a/src/packages/StorageBucketApi.ts b/src/packages/StorageBucketApi.ts
@@ -9,6 +9,7 @@ export default class StorageBucketApi {
   protected url: string
   protected headers: { [key: string]: string }
   protected fetch: Fetch
+  protected shouldThrowOnError = false
 
   constructor(
     url: string,
@@ -32,6 +33,14 @@ export default class StorageBucketApi {
     this.fetch = resolveFetch(fetch)
   }
 
+  /**
+   * Enable throwing errors instead of returning them.
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
   /**
    * Retrieves the details of all Storage buckets within an existing project.
    */
@@ -49,6 +58,9 @@ export default class StorageBucketApi {
       const data = await get(this.fetch, `${this.url}/bucket`, { headers: this.headers })
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -78,6 +90,9 @@ export default class StorageBucketApi {
       const data = await get(this.fetch, `${this.url}/bucket/${id}`, { headers: this.headers })
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -137,6 +152,9 @@ export default class StorageBucketApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -189,6 +207,9 @@ export default class StorageBucketApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -223,6 +244,9 @@ export default class StorageBucketApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -258,6 +282,9 @@ export default class StorageBucketApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
@@ -46,6 +46,7 @@ export default class StorageFileApi {
   protected headers: { [key: string]: string }
   protected bucketId?: string
   protected fetch: Fetch
+  protected shouldThrowOnError = false
 
   constructor(
     url: string,
@@ -59,6 +60,14 @@ export default class StorageFileApi {
     this.fetch = resolveFetch(fetch)
   }
 
+  /**
+   * Enable throwing errors instead of returning them.
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
   /**
    * Uploads a file to an existing bucket or replaces an existing file at the specified path with a new one.
    *
@@ -132,6 +141,9 @@ export default class StorageFileApi {
         error: null,
       }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -209,6 +221,9 @@ export default class StorageFileApi {
         error: null,
       }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -263,6 +278,9 @@ export default class StorageFileApi {
 
       return { data: { signedUrl: url.toString(), path, token }, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -339,6 +357,9 @@ export default class StorageFileApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -382,6 +403,9 @@ export default class StorageFileApi {
       )
       return { data: { path: data.Key }, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -428,6 +452,9 @@ export default class StorageFileApi {
       data = { signedUrl }
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -478,6 +505,9 @@ export default class StorageFileApi {
         error: null,
       }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -519,6 +549,9 @@ export default class StorageFileApi {
       const data = await res.blob()
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -552,6 +585,9 @@ export default class StorageFileApi {
 
       return { data: recursiveToCamel(data) as Camelize<FileObjectV2>, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -585,6 +621,9 @@ export default class StorageFileApi {
 
       return { data: true, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error) && error instanceof StorageUnknownError) {
         const originalError = (error.originalError as unknown) as { status: number }
 
@@ -664,6 +703,9 @@ export default class StorageFileApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -765,6 +807,9 @@ export default class StorageFileApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
@@ -802,6 +847,9 @@ export default class StorageFileApi {
       )
       return { data, error: null }
     } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
       if (isStorageError(error)) {
         return { data: null, error }
       }
diff --git a/test/storageBucketApi.test.ts b/test/storageBucketApi.test.ts
@@ -85,6 +85,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe(`headers must have required property 'authorization'`)
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().listBuckets()).rejects.toThrowError(
+        "headers must have required property 'authorization'"
+      )
     })
 
     it('handles network errors', async () => {
@@ -96,6 +101,9 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().listBuckets()).rejects.toThrowError('Network failure')
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -110,6 +118,9 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).toBeInstanceOf(StorageUnknownError)
       expect(error?.message).toBe('Invalid argument')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().listBuckets()).rejects.toThrowError('Invalid argument')
     })
 
     it('throws non-StorageError exceptions', async () => {
@@ -142,6 +153,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().getBucket('non-existent-bucket')).rejects.toThrow(
+        'Network failure'
+      )
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -188,6 +204,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().createBucket('new-bucket')).rejects.toThrow(
+        'Network failure'
+      )
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -234,6 +255,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(
+        storage.throwOnError().updateBucket('existing-bucket', { public: true })
+      ).rejects.toThrow('Network failure')
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -280,6 +306,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().emptyBucket('existing-bucket')).rejects.toThrow(
+        'Network failure'
+      )
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -326,6 +357,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).not.toBeNull()
       expect(error?.message).toBe('Network failure')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().deleteBucket('existing-bucket')).rejects.toThrow(
+        'Network failure'
+      )
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -338,6 +374,11 @@ describe('Bucket API Error Handling', () => {
       expect(data).toBeNull()
       expect(error).toBeInstanceOf(StorageUnknownError)
       expect(error?.message).toBe('Invalid delete operation')
+
+      // throws when .throwOnError is enabled
+      await expect(storage.throwOnError().deleteBucket('test-bucket')).rejects.toThrow(
+        'Invalid delete operation'
+      )
     })
 
     it('throws non-StorageError exceptions', async () => {
diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
