fix(storage): improve FileObject type accuracy with nullable fields (supabase#2116)

mandarini · web-flow · commit c338e2fc24ce · 2026-03-05T17:03:38.000+02:00
diff --git a/packages/core/storage-js/src/lib/types.ts b/packages/core/storage-js/src/lib/types.ts
@@ -44,34 +44,98 @@ export interface AnalyticBucket {
   updated_at: string
 }
 
+/**
+ * Metadata object returned by the Storage API for files
+ * Contains information about file size, type, caching, and HTTP response details
+ */
+export interface FileMetadata {
+  /** Entity tag for caching and conditional requests */
+  eTag: string
+  /** File size in bytes */
+  size: number
+  /** MIME type of the file */
+  mimetype: string
+  /** Cache control directive (e.g., "max-age=3600") */
+  cacheControl: string
+  /** Last modification timestamp (ISO 8601) */
+  lastModified: string
+  /** Content length in bytes (usually same as size) */
+  contentLength: number
+  /** HTTP status code from the storage backend */
+  httpStatusCode: number
+  /** Any additional custom metadata stored with the file */
+  [key: string]: any
+}
+
+/**
+ * File object returned by the List V1 API (list() method)
+ * Note: Folder entries will have null values for most fields except name
+ *
+ * Warning: Some fields may not be present in all API responses. Fields like
+ * bucket_id, owner, and buckets are not returned by list() operations.
+ */
 export interface FileObject {
+  /** File or folder name (relative to the prefix) - always present */
   name: string
-  bucket_id: string
-  owner: string
-  id: string
-  updated_at: string
-  created_at: string
-  /** @deprecated */
-  last_accessed_at: string
-  metadata: Record<string, any>
-  buckets: Bucket
+  /** Unique identifier for the file (null for folders) */
+  id: string | null
+  /** Last update timestamp (null for folders) */
+  updated_at: string | null
+  /** Creation timestamp (null for folders) */
+  created_at: string | null
+  /** @deprecated Last access timestamp (null for folders) */
+  last_accessed_at: string | null
+  /** File metadata including size, mimetype, etc. (null for folders) */
+  metadata: FileMetadata | null
+  /**
+   * @deprecated Bucket identifier - NOT returned by list() operations.
+   * May be present in remove() responses. Do not rely on this field.
+   */
+  bucket_id?: string
+  /**
+   * @deprecated Owner identifier - NOT returned by list() or remove() operations.
+   * This field should not be relied upon.
+   */
+  owner?: string
+  /**
+   * @deprecated Bucket object - NOT returned by list() or remove() operations.
+   * This field should not be relied upon.
+   */
+  buckets?: Bucket
 }
 
+/**
+ * File object returned by the Info endpoint (info() method)
+ * Contains detailed metadata for a specific file
+ */
 export interface FileObjectV2 {
+  /** Unique identifier for the file */
   id: string
+  /** File version identifier */
   version: string
+  /** File name */
   name: string
+  /** Bucket identifier */
   bucket_id: string
-  updated_at: string
+  /** Creation timestamp */
   created_at: string
-  /** @deprecated */
-  last_accessed_at: string
+  /** File size in bytes */
   size?: number
+  /** Cache control header value */
   cache_control?: string
+  /** MIME content type */
   content_type?: string
+  /** Entity tag for caching */
   etag?: string
+  /** Last modification timestamp (replaces updated_at) */
   last_modified?: string
-  metadata?: Record<string, any>
+  /** Custom file metadata */
+  metadata?: FileMetadata
+  /**
+   * @deprecated The API returns last_modified instead.
+   * This field may not be present in responses.
+   */
+  updated_at?: string
 }
 
 export interface SortBy {
@@ -175,20 +239,37 @@ export interface SearchV2Options {
   sortBy?: SortByV2
 }
 
+/**
+ * File object returned by the List V2 API (listV2() method)
+ * Objects and folders are returned in separate arrays - this type represents
+ * actual files only. Use SearchV2Folder for folder entries.
+ */
 export interface SearchV2Object {
-  id: string
-  key: string
+  /** File name */
   name: string
+  /** Full object key/path */
+  key?: string
+  /** Unique identifier for the file */
+  id: string
+  /** Last update timestamp */
   updated_at: string
+  /** Creation timestamp */
   created_at: string
-  metadata: Record<string, any>
-  /**
-   * @deprecated
-   */
+  /** File metadata including size, mimetype, etc. (null if not yet set) */
+  metadata: FileMetadata | null
+  /** @deprecated Last access timestamp */
   last_accessed_at: string
 }
 
-export type SearchV2Folder = Omit<SearchV2Object, 'id' | 'metadata' | 'last_accessed_at'>
+/**
+ * Folder entry returned by the List V2 API (listV2() method) when using with_delimiter: true
+ */
+export interface SearchV2Folder {
+  /** Folder name/prefix */
+  name: string
+  /** Full folder key/path */
+  key?: string
+}
 
 export interface SearchV2Result {
   hasNext: boolean
diff --git a/packages/core/storage-js/src/packages/StorageFileApi.ts b/packages/core/storage-js/src/packages/StorageFileApi.ts
@@ -777,6 +777,9 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
   /**
    * Retrieves the details of an existing file.
    *
+   * Returns detailed file metadata including size, content type, and timestamps.
+   * Note: The API returns `last_modified` field, not `updated_at`.
+   *
    * @category File Buckets
    * @param path The file path, including the file name. For example `folder/image.png`.
    * @returns Promise with response containing file metadata or error
@@ -787,6 +790,11 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
    *   .storage
    *   .from('avatars')
    *   .info('folder/avatar1.png')
+   *
+   * if (data) {
+   *   console.log('Last modified:', data.lastModified)
+   *   console.log('Size:', data.size)
+   * }
    * ```
    */
   async info(path: string): Promise<
@@ -951,6 +959,9 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
   /**
    * Deletes files within the same bucket
    *
+   * Returns an array of FileObject entries for the deleted files. Note that deprecated
+   * fields like `bucket_id` may or may not be present in the response - do not rely on them.
+   *
    * @category File Buckets
    * @param paths An array of files to delete, including the path and file name. For example [`'folder/image.png'`].
    * @returns Promise with response containing array of deleted file objects or error
@@ -1057,11 +1068,16 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
   /**
    * Lists all the files and folders within a path of the bucket.
    *
+   * **Important:** For folder entries, fields like `id`, `updated_at`, `created_at`,
+   * `last_accessed_at`, and `metadata` will be `null`. Only files have these fields populated.
+   * Additionally, deprecated fields like `bucket_id`, `owner`, and `buckets` are NOT returned
+   * by this method.
+   *
    * @category File Buckets
    * @param path The folder path.
    * @param options Search options including limit (defaults to 100), offset, sortBy, and search
    * @param parameters Optional fetch parameters including signal for cancellation
-   * @returns Promise with response containing array of files or error
+   * @returns Promise with response containing array of files/folders or error
    *
    * @example List files in a bucket
    * ```js
@@ -1073,9 +1089,20 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
    *     offset: 0,
    *     sortBy: { column: 'name', order: 'asc' },
    *   })
+   *
+   * // Handle files vs folders
+   * data?.forEach(item => {
+   *   if (item.id !== null) {
+   *     // It's a file
+   *     console.log('File:', item.name, 'Size:', item.metadata?.size)
+   *   } else {
+   *     // It's a folder
+   *     console.log('Folder:', item.name)
+   *   }
+   * })
    * ```
    *
-   * Response:
+   * Response (file entry):
    * ```json
    * {
    *   "data": [
@@ -1140,11 +1167,50 @@ export default class StorageFileApi extends BaseApiClient<StorageError> {
   }
 
   /**
+   * Lists all the files and folders within a bucket using the V2 API with pagination support.
+   *
+   * **Important:** Folder entries in the `folders` array only contain `name` and optionally `key` —
+   * they have no `id`, timestamps, or `metadata` fields. Full file metadata is only available
+   * on entries in the `objects` array.
+   *
    * @experimental this method signature might change in the future
    *
    * @category File Buckets
-   * @param options search options
-   * @param parameters
+   * @param options Search options including prefix, cursor for pagination, limit, with_delimiter
+   * @param parameters Optional fetch parameters including signal for cancellation
+   * @returns Promise with response containing folders/objects arrays with pagination info or error
+   *
+   * @example List files with pagination
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .listV2({
+   *     prefix: 'folder/',
+   *     limit: 100,
+   *   })
+   *
+   * // Handle pagination
+   * if (data?.hasNext) {
+   *   const nextPage = await supabase
+   *     .storage
+   *     .from('avatars')
+   *     .listV2({
+   *       prefix: 'folder/',
+   *       cursor: data.nextCursor,
+   *     })
+   * }
+   *
+   * // Handle files vs folders
+   * data?.objects.forEach(file => {
+   *   if (file.id !== null) {
+   *     console.log('File:', file.name, 'Size:', file.metadata?.size)
+   *   }
+   * })
+   * data?.folders.forEach(folder => {
+   *   console.log('Folder:', folder.name)
+   * })
+   * ```
    */
   async listV2(
     options?: SearchV2Options,
diff --git a/packages/core/storage-js/test/storageFileApi.test.ts b/packages/core/storage-js/test/storageFileApi.test.ts
@@ -336,8 +336,18 @@ describe('Object API', () => {
       expect(res.data).toEqual([
         expect.objectContaining({
           name: uploadPath.replace('testpath/', ''),
+          id: expect.any(String), // Files should have non-null id
+          metadata: expect.any(Object), // Files should have metadata
         }),
       ])
+      assert(res.data)
+
+      // Verify files have non-null required fields
+      const fileObj = res.data[0]
+      expect(fileObj.id).not.toBeNull()
+      expect(fileObj.metadata).not.toBeNull()
+      expect(fileObj.updated_at).not.toBeNull()
+      expect(fileObj.created_at).not.toBeNull()
     })
 
     test('list objects V2', async () => {
@@ -520,10 +530,17 @@ describe('Object API', () => {
       expect(res.error).toBeNull()
       expect(res.data).toEqual([
         expect.objectContaining({
-          bucket_id: bucketName,
           name: uploadPath,
+          id: expect.any(String), // Verify it's a file, not a folder
         }),
       ])
+      assert(res.data)
+
+      // bucket_id may be present in remove() responses (deprecated field)
+      // If present, verify it matches
+      if (res.data[0].bucket_id) {
+        expect(res.data[0].bucket_id).toBe(bucketName)
+      }
     })
 
     test('get object info', async () => {
@@ -545,6 +562,20 @@ describe('Object API', () => {
           version: expect.any(String),
         })
       )
+      assert(res.data)
+
+      // Verify FileObjectV2 required fields
+      expect(res.data.id).toBeDefined()
+      expect(res.data.bucketId).toBeDefined()
+      expect(res.data.lastModified).toBeDefined() // Should have this
+      expect(res.data.size).toBeGreaterThan(0)
+      expect(res.data.contentType).toBeDefined()
+      expect(res.data.cacheControl).toBeDefined()
+      expect(res.data.etag).toBeDefined()
+
+      // Verify updated_at does NOT exist (API returns camelCase, but the raw type shouldn't have it)
+      // Note: The info() method uses Camelize so we check the camelCase version
+      expect(res.data).not.toHaveProperty('updatedAt')
 
       // throws when .throwOnError is enabled
       await expect(storage.from(bucketName).throwOnError().info('non-existent')).rejects.toThrow()
