Supabase.Storage.File (supabase_storage v0.5.0)

Represents an Object within a Supabase Storage Bucket.

This module encapsulates the structure and operations related to an object or file stored within a Supabase Storage bucket.

Summary

Types

t()

An Object has the following attributes

Functions

copy(s, opts \\ [])

Copies an existing file to a new path in the same bucket.

create_signed_upload_url(s, object_path, opts \\ [])

Creates a signed upload URL.

create_signed_url(s, path, opts \\ [])

Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.

create_signed_urls(s, paths, opts \\ [])

Creates signed URLs for multiple files within a bucket.

download(s, path, opts \\ [])

Downloads a file from a private bucket. For public buckets, make a request to the URL returned from getPublicUrl instead.

download_lazy(s, path, on_response, opts \\ [])

Downloads a file from a private bucket, lazily. For public buckets, make a request to the URL returned from getPublicUrl instead.

exists?(s, path)

Checks the existence of a file.

get_public_url(s, path, opts \\ [])

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.

info(s, path)

Retrieves the details of an existing file.

list(s, prefix \\ nil, opts \\ %{})

Lists all the files within a bucket.

list_v2(s, prefix \\ nil, opts \\ %{})

Lists files using cursor-based pagination (v2 API - Experimental).

move(s, opts \\ [])

Moves an existing file to a new path in the same bucket.

remove(s, to_remove)

Deletes files within the same bucket

update(s, file_path, object_path, opts \\ %{})

Update a file in the storage bucket.

upload(s, file_path, object_path, opts \\ %{})

Uploads a file to an existing bucket.

upload_to_signed_url(s, token, file_path, object_path, opts \\ %{})

Upload a file with a token generated from create_signed_upload_url/3.

Types

t()

@type t() :: %Supabase.Storage.File{
  bucket: Supabase.Storage.Bucket.t() | nil,
  bucket_id: String.t() | nil,
  created_at: NaiveDateTime.t(),
  id: String.t(),
  last_accessed_at: NaiveDateTime.t(),
  metadata: map(),
  name: String.t(),
  owner: String.t(),
  path: Path.t(),
  updated_at: NaiveDateTime.t()
}

An Object has the following attributes:

id: The unique identifier for the object.
path: The path to the object within its storage bucket.
bucket_id: The ID of the bucket that houses this object.
name: The name or title of the object.
owner: The owner or uploader of the object.
metadata: A map containing meta-information about the object (e.g., file type, size).
created_at: Timestamp indicating when the object was first uploaded or created.
updated_at: Timestamp indicating the last time the object was updated.
last_accessed_at: Timestamp of when the object was last accessed or retrieved.

Functions

copy(s, opts \\ [])

@spec copy(Supabase.Storage.t(), options) :: Supabase.result(:moved)
when options: [
       from: Path.t(),
       to: Path.t(),
       destination_bucket: String.t() | nil
     ]

Copies an existing file to a new path in the same bucket.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
options.from: The original file path, including the current file name. For example folder/image.png.
options.to: The new file path, including the new file name. For example folder/image-new.png.
options.destination_bucket: The destination bucket ID to move the file if the options.to param refers to another bucket.

create_signed_upload_url(s, object_path, opts \\ [])

@spec create_signed_upload_url(Supabase.Storage.t(), Path.t(), [{:upsert, boolean()}]) ::
  Supabase.result(%{signed_url: String.t(), token: String.t(), path: Path.t()})

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.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
obejct_path: The file path, including the current file name. For example folder/image.png.
options.upsert: If set to true, allows the file to be overwritten if it already exists.

create_signed_url(s, path, opts \\ [])

@spec create_signed_url(Supabase.Storage.t(), object_path, options) ::
  Supabase.result(String.t())
when object_path: Path.t(),
     options: [
       download: boolean() | String.t() | nil,
       transform: Enumerable.t() | nil,
       expires_in: integer()
     ]

Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
object_path:The file path, including the current file name. For example folder/image.png.
options.expires_in: The number of seconds until the signed URL expires. For example, 60 for a URL which is valid for one minute.
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.
options.transform: An Enumerable that represents the Supabase.Storage.TransformOptions to transform the asset before serving it to the client.

create_signed_urls(s, paths, opts \\ [])

@spec create_signed_urls(Supabase.Storage.t(), [object_path], options) ::
  Supabase.result([result])
when object_path: Path.t(),
     result: %{path: String.t(), signed_url: String.t(), error: term() | nil},
     options: [
       download: boolean() | String.t() | nil,
       transform: Enumerable.t() | nil,
       expires_in: integer()
     ]

Creates signed URLs for multiple files within a bucket.

## Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
paths: A list of file paths to create signed URLs for.
opts: A keyword list of options.

## Options

:download: A boolean or string indicating whether to download the file.
:transform: An enumerable of transformations to apply to the file.
:expires_in: An integer indicating the expiration time in seconds.

## Returns

A Supabase.result containing a list of signed URLs.

download(s, path, opts \\ [])

@spec download(Supabase.Storage.t(), path :: Path.t(), options) ::
  Supabase.result(binary())
when options: [{:transform, Enumerable.t() | nil}]

Downloads a file from a private bucket. For public buckets, make a request to the URL returned from getPublicUrl instead.

Params

path: The full path and file name of the file to be downloaded. For example folder/image.png.
options.transform: Transform the asset before serving it to the client.

download_lazy(s, path, on_response, opts \\ [])

@spec download_lazy(Supabase.Storage.t(), path :: Path.t(), on_response, options) ::
  Supabase.result(binary())
when options: [{:transform, Enumerable.t() | nil}],
     on_response: ({Supabase.Fetcher.status(), Supabase.Fetcher.headers(),
                    binary()} ->
                     Supabase.result(Supabase.Fetcher.Response.t()))

Downloads a file from a private bucket, lazily. For public buckets, make a request to the URL returned from getPublicUrl instead.

Params

path: The full path and file name of the file to be downloaded. For example folder/image.png.
options.transform: Transform the asset before serving it to the client.

exists?(s, path)

@spec exists?(Supabase.Storage.t(), path :: Path.t()) :: boolean()

Checks the existence of a file.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
path

get_public_url(s, path, opts \\ [])

@spec get_public_url(Supabase.Storage.t(), object_path, options) ::
  Supabase.result(String.t())
when object_path: Path.t(),
     options: [
       download: boolean() | String.t() | nil,
       transform: Enumerable.t() | nil
     ]

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.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
path: The path and name of the file to generate the public URL for. For example folder/image.png.
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.
options.transform: Supabase.Storage.TransformOptions the asset before serving it to the client, as an Enumerable.

info(s, path)

@spec info(Supabase.Storage.t(), path :: Path.t()) :: Supabase.result(t())

Retrieves the details of an existing file.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
path

list(s, prefix \\ nil, opts \\ %{})

@spec list(Supabase.Storage.t(), Path.t() | nil, options :: Enumerable.t()) ::
  Supabase.result([t()])

Lists all the files within a bucket.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
prefix: The folder path.
options: An Enumerable that represents the Elixir.Supabase.Storage.SearchOptions.

list_v2(s, prefix \\ nil, opts \\ %{})

@spec list_v2(Supabase.Storage.t(), Path.t() | nil, options :: Enumerable.t()) ::
  Supabase.result(%{
    has_next: boolean(),
    cursor: String.t() | nil,
    folders: [String.t()],
    objects: [t()]
  })

Lists files using cursor-based pagination (v2 API - Experimental).

This method uses cursor-based pagination which is more efficient than offset-based pagination for large datasets. Cursor pagination has O(1) complexity regardless of the position in the dataset, while offset pagination becomes slower as the offset increases.

Performance Comparison

Offset-based: OFFSET 100000 LIMIT 100 - Very slow (must skip 100,000 records)
Cursor-based: Always fast regardless of position

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
prefix: The folder path.
options: An Enumerable with the following keys:
- limit: Number of results per page (default: 100)
- cursor: Pagination cursor from previous response
- with_delimiter: Enable folder hierarchy grouping (default: false)

Returns

A map with:

has_next: Boolean indicating if there are more pages
cursor: Cursor to use for the next page (if has_next is true)
folders: List of folder names (when with_delimiter is true)
objects: List of file objects

Examples

# First page
{:ok, %{has_next: true, cursor: cursor, objects: files}} =
  Supabase.Storage.File.list_v2(storage, "public/", %{limit: 100})

# Next page using cursor
{:ok, %{has_next: false, objects: more_files}} =
  Supabase.Storage.File.list_v2(storage, "public/", %{limit: 100, cursor: cursor})

# With folder hierarchy
{:ok, %{folders: folders, objects: files}} =
  Supabase.Storage.File.list_v2(storage, "public/", %{with_delimiter: true})

move(s, opts \\ [])

@spec move(Supabase.Storage.t(), options) :: Supabase.result(:moved)
when options: [
       from: Path.t(),
       to: Path.t(),
       destination_bucket: String.t() | nil
     ]

Moves an existing file to a new path in the same bucket.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
options.from: The original file path, including the current file name. For example folder/image.png.
options.to: The new file path, including the new file name. For example folder/image-new.png.
options.destination_bucket: The destination bucket ID to move the file if the options.to param refers to another bucket.

remove(s, to_remove)

@spec remove(Supabase.Storage.t(), to_remove :: [Path.t()] | Path.t()) ::
  Supabase.result([t()] | t())

Deletes files within the same bucket

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
paths: An array of files to delete, including the path and file name. For example ["folder/image.png"].

update(s, file_path, object_path, opts \\ %{})

@spec update(Supabase.Storage.t(), file_path, object_path, options) ::
  Supabase.result(map())
when file_path: Path.t(), object_path: Path.t(), options: Enumerable.t()

Update a file in the storage bucket.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
file_path: The local filesystem path, to upload from.
object_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.
options: Optional Enumerable that represents the Supabase.Storage.FileOptions.

upload(s, file_path, object_path, opts \\ %{})

@spec upload(Supabase.Storage.t(), file_path, object_path, options) ::
  Supabase.result(map())
when file_path: Path.t(), object_path: Path.t(), options: Enumerable.t()

Uploads a file to an existing bucket.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
file_path: The local filesystem path, to upload from.
object_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.
options: Optional Enumerable that represents the Supabase.Storage.FileOptions.

upload_to_signed_url(s, token, file_path, object_path, opts \\ %{})

@spec upload_to_signed_url(
  Supabase.Storage.t(),
  token,
  file_path,
  object_path,
  options
) ::
  Supabase.result(map())
when file_path: Path.t(),
     object_path: Path.t(),
     options: Enumerable.t(),
     token: String.t()

Upload a file with a token generated from create_signed_upload_url/3.

Params

storage: The Supabase.Storage instance created with Supabase.Storage.from/2.
token: token The token generated from create_signed_upload_url/3.
file_path: The local filesystem path, to upload from.
object_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.
options: Optional Enumerable that represents the Supabase.Storage.FileOptions.