fix(storage)!: do not throw error when file does not exist in exists method (#1838)

Co-authored-by: Sumit Kumar <sumitkumar@kgpian.iitkgp.ac.in>

Author: mandarini

packages/core/storage-js/src/packages/StorageFileApi.ts

@@ -967,7 +967,7 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
    * @category Storage
    * @subcategory File Buckets
    * @param path The file path, including the file name. For example `folder/image.png`.
-   * @returns Promise with response containing boolean indicating file existence or error
+   * @returns `{ data: true, error: null }` when the file exists, `{ data: false, error: null }` when it does not (HTTP 400 or 404), or throws/returns a `StorageError` for any other failure.
    *
    * @example Check file existence
    * ```js
@@ -1009,7 +1009,7 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
               : undefined
 
         if (status !== undefined && [400, 404].includes(status)) {
-          return { data: false, error }
+          return { data: false, error: null }
         }
       }
 

packages/core/storage-js/test/storageFileApi.test.ts

@@ -614,6 +614,7 @@ describe('Object API', () => {
 
       const resNotExists = await storage.from(bucketName).exists('do-not-exists')
       expect(resNotExists.data).toEqual(false)
+      expect(resNotExists.error).toBeNull()
 
       // should throw when .throwOnError is enabled
       await expect(

packages/core/storage-js/test/storageFileApiErrorHandling.test.ts

@@ -239,6 +239,43 @@ describe('File API Error Handling', () => {
     })
   })
 
+  describe('exists', () => {
+    it('returns { data: false, error: null } when the file does not exist (404)', async () => {
+      global.fetch = jest.fn().mockResolvedValue(new Response(null, { status: 404 }))
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).exists('missing.jpg')
+      expect(data).toBe(false)
+      expect(error).toBeNull()
+    })
+
+    it('returns { data: false, error: null } when the server responds 400 (current Storage API behavior for missing objects)', async () => {
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify({ message: 'Bad Request' }), { status: 400 })
+        )
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).exists('whatever.jpg')
+      expect(data).toBe(false)
+      expect(error).toBeNull()
+    })
+
+    it('surfaces an error for genuine failures (e.g., 500 server error)', async () => {
+      global.fetch = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(JSON.stringify({ message: 'Internal Server Error' }), { status: 500 })
+        )
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      await expect(storage.from(BUCKET_ID).exists('whatever.jpg')).rejects.toBeInstanceOf(
+        StorageError
+      )
+    })
+  })
+
   describe('createSignedUrl', () => {
     it('handles network errors', async () => {
       const mockError = new Error('Network failure')