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

Breaking change

This is a breaking change, and it can be added in the v3 planning.

[coveralls]

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

[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.

[mandarini]

I will be parking this PR for now, since it will be a breaking change. We will consider this change for our v3 release. Thank you @SumitKumar-17

[SumitKumar-17]

Okay @mandarini