# `Aludel.Storage`
[🔗](https://github.com/ccarvalho-eng/aludel/blob/main/lib/aludel/interfaces/storage.ex#L1)

Domain-facing facade for document storage backends.

Test case documents are persisted through the configured storage adapter.

# `config`

```elixir
@type config() :: keyword()
```

# `error_reason`

```elixir
@type error_reason() :: term()
```

# `adapter`

```elixir
@spec adapter() :: module()
```

Returns the currently configured storage adapter.

The local filesystem adapter is used when no adapter is configured.

# `backend_name`

```elixir
@spec backend_name(module()) :: String.t()
```

Returns the stable persisted name for a storage adapter.

# `config`

```elixir
@spec config() :: config()
```

Returns the resolved application storage configuration.

# `delete`

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

Deletes a storage key through its owning backend.

Accepts the same `:storage_backend` and `:config` options as `get/2`.

# `get`

```elixir
@spec get(String.t(), keyword()) :: {:ok, binary()} | {:error, error_reason()}
```

Reads a storage key through its owning backend.

Use `:storage_backend` to select a named historical backend and `:config` to
overlay adapter configuration for this operation.

# `put`

```elixir
@spec put(String.t(), binary(), String.t()) ::
  {:ok, String.t()} | {:error, error_reason()}
```

Persists document contents through the configured adapter and returns the
adapter-specific storage key to save with the document row.

# `read`

```elixir
@spec read(Aludel.Evals.TestCaseDocument.t()) ::
  {:ok, binary()} | {:error, error_reason()}
```

Reads the contents associated with a test case document.

The document's persisted backend name is honored, allowing records created
before a backend switch to remain readable. Documents without storage
metadata return `{:error, :missing_document_data}`.

# `resolve_backend`

```elixir
@spec resolve_backend(String.t() | nil) ::
  {:ok, module()} | {:error, :unknown_storage_backend}
```

Resolves a persisted backend name to a storage adapter module.

`nil` selects the active adapter. Unknown names return
`{:error, :unknown_storage_backend}` without creating atoms.

# `storage_key`

```elixir
@spec storage_key(Ecto.UUID.t(), String.t()) :: String.t()
```

Builds a namespaced storage key for an uploaded document.

Directory components are removed from the filename and unsupported
characters are replaced with underscores.

---

*Consult [api-reference.md](api-reference.md) for complete listing*