fix(storage): correct exists() error handling for non-existent files

[mandarini]

authored by @SumitKumar-17
Transfered from: supabase/storage-js#256

Bug Fix Report

I have successfully identified and fixed the bug reported in the
issue. Here's what I found and resolved:

The Issue

The bug report was partially correct. The exists method was indeed
present in both browser and Node.js builds (I confirmed it existed
in the compiled output), but there was an error handling bug that
made it appear to not work properly in certain cases.

The Root Cause

The problem was in the error handling logic of the exists method in
src/packages/StorageFileApi.ts. When a file doesn't exist
(resulting in a 404 HTTP status), the method would return { data: false, error: StorageError } instead of { data: false, error: null }.
This was incorrect behavior because:

1. The operation (checking for existence) was successful
2. Getting a 404 simply means the file doesn't exist, not that the
   operation failed
3. The user should receive { data: false, error: null } to indicate
   "file doesn't exist, but the check was successful"

The Fix

I updated the exists method to properly handle both
StorageApiError (which contains the status code directly) and
StorageUnknownError (which contains the original error object),
and return { data: false, error: null } when the error status is
400 or 404.

Changes Made

1. Fixed error handling in the exists method to properly return { data: false, error: null } when a file doesn't exist
2. Added proper TypeScript imports for StorageApiError
3. Updated README documentation with an example of how to use the
   exists method

Verification

• The project builds successfully with the fix
• The method is available in all builds (main, module, UMD)
• The fix aligns with the existing test expectations
• Proper TypeScript types are maintained

Solves: #1600

[coveralls]

coverage: 95.455% (+13.0%) from 82.5%
when pulling 195ca1b on fix/storage-exists-frontend
into 2d0bd77 on master.

[itslenny]

I agree that it makes more sense to only get data OR error, but this would for sure be a breaking change for some people.

It seems very likely that at least some projects use code like this which would exhibit reveresed logic because of this change.

const { data, error } = storage.exists('some/path.jpg)

if (error) {
  // potentially also checks if it's a NotFound error
  // do "not exists" stuff
}

// do "exists" stuff

I think we still have to return error instead of null to avoid a major breaking change.

Plus, the return type allows for it, and it's like saying "exists is false BECAUSE... (a 400 or 404 error)"

[mandarini]

@SumitKumar-17 what do you think, do you want to work on these changes?

[SumitKumar-17]

@mandarini Ya let me look into it.

[SumitKumar-17]

@itslenny I think this can work

if (status && [400, 404].indexOf(status) !== -1) {
          return { data: false, error }
        }

Users checking if (error) will correctly trigger the "not exists" logic when files don't exist

The Return Type Supports It
The TypeScript return type already allows for both scenarios:
So returning the actual error object is perfectly valid and expected.

Promise<
  | { data: boolean; error: null }
  | { data: boolean; error: StorageError }
>

The change ensures that users can properly handle both "file exists" and "file doesn't exist" scenarios using the error field, which is the standard pattern in Supabase APIs.