@supabase/storage-js 2.81.2-canary.2 → 2.82.0

package/src/packages/StorageFileApi.ts

@@ -63,6 +63,8 @@ export default class StorageFileApi {
 
   /**
    * Enable throwing errors instead of returning them.
+   *
+   * @category File Buckets
    */
   public throwOnError(): this {
     this.shouldThrowOnError = true
@@ -169,8 +171,46 @@ export default class StorageFileApi {
   /**
    * Uploads a file to an existing bucket.
    *
+   * @category File Buckets
    * @param path The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
    * @param fileBody The body of the file to be stored in the bucket.
+   * @param fileOptions Optional file upload options including cacheControl, contentType, upsert, and metadata.
+   * @returns Promise with file path and id or error
+   *
+   * @example Upload file
+   * ```js
+   * const avatarFile = event.target.files[0]
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .upload('public/avatar1.png', avatarFile, {
+   *     cacheControl: '3600',
+   *     upsert: false
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "path": "public/avatar1.png",
+   *     "fullPath": "avatars/public/avatar1.png"
+   *   },
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Upload file using `ArrayBuffer` from base64 file data
+   * ```js
+   * import { decode } from 'base64-arraybuffer'
+   *
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .upload('public/avatar1.png', decode('base64FileData'), {
+   *     contentType: 'image/png'
+   *   })
+   * ```
    */
   async upload(
     path: string,
@@ -191,9 +231,32 @@ export default class StorageFileApi {
 
   /**
    * Upload a file with a token generated from `createSignedUploadUrl`.
+   *
+   * @category File Buckets
    * @param path The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
    * @param token The token generated from `createSignedUploadUrl`
    * @param fileBody The body of the file to be stored in the bucket.
+   * @param fileOptions Optional file upload options including cacheControl and contentType.
+   * @returns Promise with file path and full path or error
+   *
+   * @example Upload to a signed URL
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .uploadToSignedUrl('folder/cat.jpg', 'token-from-createSignedUploadUrl', file)
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "path": "folder/cat.jpg",
+   *     "fullPath": "avatars/folder/cat.jpg"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async uploadToSignedUrl(
     path: string,
@@ -250,8 +313,31 @@ export default class StorageFileApi {
    * Creates a signed upload URL.
    * Signed upload URLs can be used to upload files to the bucket without further authentication.
    * They are valid for 2 hours.
+   *
+   * @category File Buckets
    * @param path The file path, including the current file name. For example `folder/image.png`.
    * @param options.upsert If set to true, allows the file to be overwritten if it already exists.
+   * @returns Promise with signed upload URL, token, and path or error
+   *
+   * @example Create Signed Upload URL
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .createSignedUploadUrl('folder/cat.jpg')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "signedUrl": "https://example.supabase.co/storage/v1/object/upload/sign/avatars/folder/cat.jpg?token=<TOKEN>",
+   *     "path": "folder/cat.jpg",
+   *     "token": "<TOKEN>"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async createSignedUploadUrl(
     path: string,
@@ -306,8 +392,46 @@ export default class StorageFileApi {
   /**
    * Replaces an existing file at the specified path with a new one.
    *
+   * @category File Buckets
    * @param path The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update.
    * @param fileBody The body of the file to be stored in the bucket.
+   * @param fileOptions Optional file upload options including cacheControl, contentType, upsert, and metadata.
+   * @returns Promise with file path and id or error
+   *
+   * @example Update file
+   * ```js
+   * const avatarFile = event.target.files[0]
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .update('public/avatar1.png', avatarFile, {
+   *     cacheControl: '3600',
+   *     upsert: true
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "path": "public/avatar1.png",
+   *     "fullPath": "avatars/public/avatar1.png"
+   *   },
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Update file using `ArrayBuffer` from base64 file data
+   * ```js
+   * import {decode} from 'base64-arraybuffer'
+   *
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .update('public/avatar1.png', decode('base64FileData'), {
+   *     contentType: 'image/png'
+   *   })
+   * ```
    */
   async update(
     path: string,
@@ -339,9 +463,29 @@ export default class StorageFileApi {
   /**
    * Moves an existing file to a new path in the same bucket.
    *
+   * @category File Buckets
    * @param fromPath The original file path, including the current file name. For example `folder/image.png`.
    * @param toPath The new file path, including the new file name. For example `folder/image-new.png`.
    * @param options The destination options.
+   * @returns Promise with success message or error
+   *
+   * @example Move file
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .move('public/avatar1.png', 'private/avatar2.png')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "message": "Successfully moved"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async move(
     fromPath: string,
@@ -385,9 +529,29 @@ export default class StorageFileApi {
   /**
    * Copies an existing file to a new path in the same bucket.
    *
+   * @category File Buckets
    * @param fromPath The original file path, including the current file name. For example `folder/image.png`.
    * @param toPath The new file path, including the new file name. For example `folder/image-copy.png`.
    * @param options The destination options.
+   * @returns Promise with copied file path or error
+   *
+   * @example Copy file
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .copy('public/avatar1.png', 'private/avatar2.png')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "path": "avatars/private/avatar2.png"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async copy(
     fromPath: string,
@@ -431,10 +595,53 @@ export default class StorageFileApi {
   /**
    * Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.
    *
+   * @category File Buckets
    * @param path The file path, including the current file name. For example `folder/image.png`.
    * @param expiresIn The number of seconds until the signed URL expires. For example, `60` for a URL which is valid for one minute.
    * @param options.download triggers the file as a download if set to true. Set this parameter as the name of the file if you want to trigger the download with a different filename.
    * @param options.transform Transform the asset before serving it to the client.
+   * @returns Promise with signed URL or error
+   *
+   * @example Create Signed URL
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .createSignedUrl('folder/avatar1.png', 60)
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "signedUrl": "https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar1.png?token=<TOKEN>"
+   *   },
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Create a signed URL for an asset with transformations
+   * ```js
+   * const { data } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .createSignedUrl('folder/avatar1.png', 60, {
+   *     transform: {
+   *       width: 100,
+   *       height: 100,
+   *     }
+   *   })
+   * ```
+   *
+   * @example Create a signed URL which triggers the download of the asset
+   * ```js
+   * const { data } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .createSignedUrl('folder/avatar1.png', 60, {
+   *     download: true,
+   *   })
+   * ```
    */
   async createSignedUrl(
     path: string,
@@ -480,9 +687,40 @@ export default class StorageFileApi {
   /**
    * Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time.
    *
+   * @category File Buckets
    * @param paths The file paths to be downloaded, including the current file names. For example `['folder/image.png', 'folder2/image2.png']`.
    * @param expiresIn The number of seconds until the signed URLs expire. For example, `60` for URLs which are valid for one minute.
    * @param options.download triggers the file as a download if set to true. Set this parameter as the name of the file if you want to trigger the download with a different filename.
+   * @returns Promise with array of signed URLs or error
+   *
+   * @example Create Signed URLs
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .createSignedUrls(['folder/avatar1.png', 'folder/avatar2.png'], 60)
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "error": null,
+   *       "path": "folder/avatar1.png",
+   *       "signedURL": "/object/sign/avatars/folder/avatar1.png?token=<TOKEN>",
+   *       "signedUrl": "https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar1.png?token=<TOKEN>"
+   *     },
+   *     {
+   *       "error": null,
+   *       "path": "folder/avatar2.png",
+   *       "signedURL": "/object/sign/avatars/folder/avatar2.png?token=<TOKEN>",
+   *       "signedUrl": "https://example.supabase.co/storage/v1/object/sign/avatars/folder/avatar2.png?token=<TOKEN>"
+   *     }
+   *   ],
+   *   "error": null
+   * }
+   * ```
    */
   async createSignedUrls(
     paths: string[],
@@ -533,8 +771,40 @@ export default class StorageFileApi {
   /**
    * Downloads a file from a private bucket. For public buckets, make a request to the URL returned from `getPublicUrl` instead.
    *
+   * @category File Buckets
    * @param path The full path and file name of the file to be downloaded. For example `folder/image.png`.
    * @param options.transform Transform the asset before serving it to the client.
+   * @returns BlobDownloadBuilder instance for downloading the file
+   *
+   * @example Download file
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .download('folder/avatar1.png')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": <BLOB>,
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Download file with transformations
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .download('folder/avatar1.png', {
+   *     transform: {
+   *       width: 100,
+   *       height: 100,
+   *       quality: 80
+   *     }
+   *   })
+   * ```
    */
   download<Options extends { transform?: TransformOptions }>(
     path: string,
@@ -555,7 +825,18 @@ export default class StorageFileApi {
 
   /**
    * Retrieves the details of an existing file.
-   * @param path
+   *
+   * @category File Buckets
+   * @param path The file path, including the file name. For example `folder/image.png`.
+   * @returns Promise with file metadata or error
+   *
+   * @example Get file info
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .info('folder/avatar1.png')
+   * ```
    */
   async info(path: string): Promise<
     | {
@@ -589,7 +870,18 @@ export default class StorageFileApi {
 
   /**
    * Checks the existence of a file.
-   * @param path
+   *
+   * @category File Buckets
+   * @param path The file path, including the file name. For example `folder/image.png`.
+   * @returns Promise with boolean indicating file existence or error
+   *
+   * @example Check file existence
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .exists('folder/avatar1.png')
+   * ```
    */
   async exists(path: string): Promise<
     | {
@@ -629,9 +921,51 @@ export default class StorageFileApi {
    * A simple convenience function to get the URL for an asset in a public bucket. If you do not want to use this function, you can construct the public URL by concatenating the bucket URL with the path to the asset.
    * This function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset.
    *
+   * @category File Buckets
    * @param path The path and name of the file to generate the public URL for. For example `folder/image.png`.
    * @param options.download Triggers the file as a download if set to true. Set this parameter as the name of the file if you want to trigger the download with a different filename.
    * @param options.transform Transform the asset before serving it to the client.
+   * @returns Object with public URL
+   *
+   * @example Returns the URL for an asset in a public bucket
+   * ```js
+   * const { data } = supabase
+   *   .storage
+   *   .from('public-bucket')
+   *   .getPublicUrl('folder/avatar1.png')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "publicUrl": "https://example.supabase.co/storage/v1/object/public/public-bucket/folder/avatar1.png"
+   *   }
+   * }
+   * ```
+   *
+   * @example Returns the URL for an asset in a public bucket with transformations
+   * ```js
+   * const { data } = supabase
+   *   .storage
+   *   .from('public-bucket')
+   *   .getPublicUrl('folder/avatar1.png', {
+   *     transform: {
+   *       width: 100,
+   *       height: 100,
+   *     }
+   *   })
+   * ```
+   *
+   * @example Returns the URL which triggers the download of an asset in a public bucket
+   * ```js
+   * const { data } = supabase
+   *   .storage
+   *   .from('public-bucket')
+   *   .getPublicUrl('folder/avatar1.png', {
+   *     download: true,
+   *   })
+   * ```
    */
   getPublicUrl(
     path: string,
@@ -669,7 +1003,25 @@ export default class StorageFileApi {
   /**
    * Deletes files within the same bucket
    *
+   * @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 list of deleted files or error
+   *
+   * @example Delete file
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .remove(['folder/avatar1.png'])
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": [],
+   *   "error": null
+   * }
+   * ```
    */
   async remove(paths: string[]): Promise<
     | {
@@ -766,8 +1118,62 @@ export default class StorageFileApi {
 
   /**
    * Lists all the files and folders within a path of the bucket.
+   *
+   * @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 list of files or error
+   *
+   * @example List files in a bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .list('folder', {
+   *     limit: 100,
+   *     offset: 0,
+   *     sortBy: { column: 'name', order: 'asc' },
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "name": "avatar1.png",
+   *       "id": "e668cf7f-821b-4a2f-9dce-7dfa5dd1cfd2",
+   *       "updated_at": "2024-05-22T23:06:05.580Z",
+   *       "created_at": "2024-05-22T23:04:34.443Z",
+   *       "last_accessed_at": "2024-05-22T23:04:34.443Z",
+   *       "metadata": {
+   *         "eTag": "\"c5e8c553235d9af30ef4f6e280790b92\"",
+   *         "size": 32175,
+   *         "mimetype": "image/png",
+   *         "cacheControl": "max-age=3600",
+   *         "lastModified": "2024-05-22T23:06:05.574Z",
+   *         "contentLength": 32175,
+   *         "httpStatusCode": 200
+   *       }
+   *     }
+   *   ],
+   *   "error": null
+   * }
+   * ```
+   *
+   * @example Search files in a bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .from('avatars')
+   *   .list('folder', {
+   *     limit: 100,
+   *     offset: 0,
+   *     sortBy: { column: 'name', order: 'asc' },
+   *     search: 'jon'
+   *   })
+   * ```
    */
   async list(
     path?: string,
@@ -807,6 +1213,8 @@ export default class StorageFileApi {
 
   /**
    * @experimental this method signature might change in the future
+   *
+   * @category File Buckets
    * @param options search options
    * @param parameters
    */