SferaDoc.Store.Adapter behaviour (sfera_doc v0.1.0)

Behaviour that all SferaDoc storage backends must implement.

Templates are identified by their name (a human-readable string). Each name can have multiple numbered versions; at most one version per name is active at any time.

Implementing a Custom Adapter

use or @behaviour SferaDoc.Store.Adapter
Implement all callbacks
Return nil from worker_spec/0 if your adapter uses an externally supervised process (e.g. an Ecto Repo managed by the host application)

Configure the library to use your adapter:

config :sfera_doc, :store, adapter: MyApp.CustomAdapter

Summary

Types

name()

reason()

version()

Callbacks

activate_version(name, version)

Makes the given version the active one for the template name. Deactivates all other versions for that name.

delete(name)

Deletes all versions of a template by name.

get(name)

Fetches the currently active template for the given name.

get_version(name, version)

Fetches a specific version of a template by name and version number.

list()

Returns all templates (latest active version per name).

list_versions(name)

Returns all versions for a given template name, ordered by version descending.

put(t)

Persists a new version of the template.

worker_spec()

Returns a child spec for processes this adapter needs, or nil if the adapter relies on externally managed processes (e.g. Ecto repos).

Types

name()

@type name() :: String.t()

reason()

@type reason() :: any()

version()

@type version() :: pos_integer()

Callbacks

activate_version(name, version)

@callback activate_version(name(), version()) ::
  {:ok, SferaDoc.Template.t()} | {:error, :not_found} | {:error, reason()}

Makes the given version the active one for the template name. Deactivates all other versions for that name.

delete(name)

@callback delete(name()) :: :ok | {:error, reason()}

Deletes all versions of a template by name.

get(name)

@callback get(name()) ::
  {:ok, SferaDoc.Template.t()} | {:error, :not_found} | {:error, reason()}

Fetches the currently active template for the given name.

get_version(name, version)

@callback get_version(name(), version()) ::
  {:ok, SferaDoc.Template.t()} | {:error, :not_found} | {:error, reason()}

Fetches a specific version of a template by name and version number.

list()

@callback list() :: {:ok, [SferaDoc.Template.t()]} | {:error, reason()}

Returns all templates (latest active version per name).

list_versions(name)

@callback list_versions(name()) :: {:ok, [SferaDoc.Template.t()]} | {:error, reason()}

Returns all versions for a given template name, ordered by version descending.

put(t)

@callback put(SferaDoc.Template.t()) :: {:ok, SferaDoc.Template.t()} | {:error, reason()}

Persists a new version of the template.

The adapter is responsible for:

computing the next version number (MAX(existing versions) + 1, or 1 if new)
setting is_active: true on the new record
setting is_active: false on all previous versions for the same name

Both create and update go through this single callback.

worker_spec()

@callback worker_spec() :: Supervisor.child_spec() | nil

Returns a child spec for processes this adapter needs, or nil if the adapter relies on externally managed processes (e.g. Ecto repos).

The supervisor filters out nil values, so returning nil is safe.