Dala.Storage.Storage (dala v0.7.0)

App-local file storage.

Provides a thin Elixir wrapper over the device filesystem using named locations instead of raw paths. Basic file operations (list, stat, delete, copy, move, read, write) are pure File.* calls — no NIF overhead except for the initial dir/1 path resolution.

Locations

:temp — ephemeral; may be purged by the OS at any time

:documents — persists across app sessions; user-visible on iOS

             when `UIFileSharingEnabled` is set (see `mix dala.enable`)

:cache — persists until OS needs space; not user-visible
:app_support — persists, hidden from user, backed up on iOS

Platform-specific storage

See Dala.Storage.Apple and Dala.Storage.Android for saving to the native photo/media library and accessing platform-specific directories.

Results

Operations that can fail return {:ok, value} | {:error, posix}. dir/1 raises on an unknown location atom.

Summary

Functions

append(path, data)

Append data to the end of a file.

copy(src, dest)

Copy src to dest.

create(path)

Create a new empty file at path.

create(path, content)

Create a new file at path with the given content.

delete(path, opts \\ [])

Delete a file or directory at path.

dir(location)

Resolve a location atom to its absolute path on the current device.

ensure_dir(path)

Ensure the parent directory for path exists, creating it if necessary.

exists?(path)

Check if a file or directory exists at path.

export(src, dest)

Export a file from a location to a destination path.

extension(path)

Return the file extension including the leading dot, or "" if none.

info(path)

Return detailed file information.

list(location)

List all files in a location or an absolute path.

move(src, dest)

Move src to dest.

read(path)

Read a file's contents as a binary.

read_text(path)

Read a file and return its contents as a string.

size(path)

Return the file size in bytes, or {:error, reason} if the file doesn't exist.

stat(path)

Return metadata for a file.

update(path, content)

Update the contents of an existing file at path.

write(path, data)

Write data to path.

write_text(path, content)

Write content to a file as text.

Functions

append(path, data)

@spec append(String.t(), binary()) :: {:ok, String.t()} | {:error, atom()}

Append data to the end of a file.

Creates the file if it doesn't exist. Returns {:ok, path} on success.

Dala.Storage.append("/tmp/log.txt", "New log entry\n")

copy(src, dest)

@spec copy(String.t(), atom() | String.t()) :: {:ok, String.t()} | {:error, atom()}

Copy src to dest.

dest may be a location atom (file is placed there keeping its basename) or a full absolute path.

Returns {:ok, dest_path} on success.

create(path)

@spec create(String.t()) :: {:ok, String.t()} | {:error, atom()}

Create a new empty file at path.

Creates parent directories if they don't exist. Returns {:ok, path} on success.

Dala.Storage.create("/tmp/new_file.txt")

create(path, content)

@spec create(String.t(), binary()) :: {:ok, String.t()} | {:error, atom()}

Create a new file at path with the given content.

Creates parent directories if they don't exist. Returns {:ok, path} on success.

Dala.Storage.create("/tmp/new_file.txt", "Hello, World!")

delete(path, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: :ok | {:error, atom()}

Delete a file or directory at path.

Use force: true to delete non-empty directories. Returns :ok on success.

Dala.Storage.delete("/tmp/old_file.txt")
Dala.Storage.delete("/tmp/old_dir", force: true)

dir(location)

@spec dir(atom()) :: String.t()

Resolve a location atom to its absolute path on the current device.

ensure_dir(path)

@spec ensure_dir(String.t()) :: :ok | {:error, atom()}

Ensure the parent directory for path exists, creating it if necessary.

Returns :ok on success.

Dala.Storage.ensure_dir("/tmp/new_dir/file.txt")

exists?(path)

@spec exists?(String.t()) :: boolean()

Check if a file or directory exists at path.

Dala.Storage.exists?("/tmp/file.txt")  #=> true

export(src, dest)

@spec export(String.t(), String.t()) :: {:ok, String.t()} | {:error, atom()}

Export a file from a location to a destination path.

Creates parent directories of dest if needed. Returns {:ok, dest_path} on success.

Dala.Storage.export("/tmp/file.txt", "/tmp/backup/file.txt")

extension(path)

@spec extension(String.t()) :: String.t()

Return the file extension including the leading dot, or "" if none.

No I/O — derived from the filename only.

Dala.Storage.extension("/tmp/clip.mp4")   #=> ".mp4"
Dala.Storage.extension("/tmp/notes")      #=> ""

info(path)

@spec info(String.t()) :: {:ok, map()} | {:error, atom()}

Return detailed file information.

Returns a map with :name, :path, :size, :modified_at, :type, and :extension.

Dala.Storage.info("/tmp/clip.mp4")
#=> %{name: "clip.mp4", path: "/tmp/clip.mp4", size: 204800,
#    modified_at: ~U[2026-04-24 10:00:00Z], type: :regular,
#    extension: ".mp4"}

list(location)

@spec list(atom() | String.t()) :: {:ok, [String.t()]} | {:error, atom()}

List all files in a location or an absolute path.

Returns full paths, not just names.

move(src, dest)

@spec move(String.t(), atom() | String.t()) :: {:ok, String.t()} | {:error, atom()}

Move src to dest.

dest may be a location atom (file is placed there keeping its basename) or a full absolute path. Creates parent directories of dest if needed.

Returns {:ok, dest_path} on success.

Dala.Storage.move("/tmp/old.txt", "/tmp/new.txt")
Dala.Storage.move("/tmp/file.txt", :documents)

read(path)

@spec read(String.t()) :: {:ok, binary()} | {:error, atom()}

Read a file's contents as a binary.

read_text(path)

@spec read_text(String.t()) :: {:ok, String.t()} | {:error, atom()}

Read a file and return its contents as a string.

Returns {:ok, content} on success.

Dala.Storage.read_text("/tmp/file.txt")  #=> {:ok, "Hello"}

size(path)

@spec size(String.t()) :: {:ok, non_neg_integer()} | {:error, atom()}

Return the file size in bytes, or {:error, reason} if the file doesn't exist.

Dala.Storage.size("/tmp/file.txt")  #=> {:ok, 1024}

stat(path)

@spec stat(String.t()) :: {:ok, map()} | {:error, atom()}

Return metadata for a file.

%{name: "clip.mp4", path: "/…/clip.mp4", size: 204_800,
  modified_at: ~U[2026-04-24 10:00:00Z]}

update(path, content)

@spec update(String.t(), binary()) :: {:ok, String.t()} | {:error, atom()}

Update the contents of an existing file at path.

Returns {:ok, path} on success. Returns {:error, :enoent} if the file doesn't exist.

Dala.Storage.update("/tmp/existing_file.txt", "Updated content")

write(path, data)

@spec write(String.t(), binary()) :: {:ok, String.t()} | {:error, atom()}

Write data to path.

Returns {:ok, path} on success.

write_text(path, content)

@spec write_text(String.t(), String.t()) :: {:ok, String.t()} | {:error, atom()}

Write content to a file as text.

Creates parent directories if they don't exist. Returns {:ok, path} on success.

Dala.Storage.write_text("/tmp/file.txt", "Hello, World!")