@spec declares?(module()) :: boolean()

Whether a module carries blind index declarations.

Code.ensure_loaded?/1 before function_exported?/2 for the reason Encryptor.Ecto.Declarations gives at its own use of the pair: the bare export check answers false for a module that is merely not loaded yet, and a check whose answer depends on load order passes in the suite that would have caught the mistake.

@spec derivation!(t()) :: Encryptor.Ecto.BlindIndex.Derivation.t()

The derivation identity this declaration keys under.

The table and column come from the encrypted field's frozen params rather than from the declaration, so an index derives under the same declared context the field encrypts under, and a physical rename moves neither.

iex> Encryptor.Ecto.BlindIndex.Declaration.fetch!(
...>   Encryptor.Ecto.TestSchemas.Customer, :email, :email_index)
...> |> Encryptor.Ecto.BlindIndex.Declaration.derivation!()
...> |> Encryptor.Ecto.BlindIndex.Derivation.info()
"encryptor_ecto/blind_index/v1|customers|email|email_index|1"

@spec fetch(module(), atom(), atom()) :: {:ok, t()} | :error

The declaration for one {source, column} pair.

iex> {:ok, declaration} =
...>   Encryptor.Ecto.BlindIndex.Declaration.fetch(
...>     Encryptor.Ecto.TestSchemas.Customer, :email, :email_index)
iex> declaration.normalize
:email

iex> Encryptor.Ecto.BlindIndex.Declaration.fetch(
...>   Encryptor.Ecto.TestSchemas.Customer, :email, :nowhere)
:error

@spec fetch!(module(), atom(), atom()) :: t()

The same, raising with what is declared when nothing matches.

The message lists the schema's declarations because the overwhelmingly likely cause is a helper naming a column that is spelled differently at the declaration, and a reader who can see both spellings at once is done.

@spec field_params(t()) ::
  {:ok, Encryptor.Ecto.BlindIndex.Derivation.field_params()}
  | {:error, resolution_error()}

The encrypted field's frozen parameters, read from the schema.

Returns {:error, :missing_field} when the source names no field and {:error, :not_encrypted} when it names one this package does not encrypt. Both are the compile-time check's material; field_params!/1 is the arm for a caller that has already been through that check.

@spec field_params!(t()) :: Encryptor.Ecto.BlindIndex.Derivation.field_params()

The same, raising for a caller past the compile-time check.

iex> Encryptor.Ecto.BlindIndex.Declaration.fetch!(
...>   Encryptor.Ecto.TestSchemas.Customer, :email, :email_index)
...> |> Encryptor.Ecto.BlindIndex.Declaration.field_params!()
...> |> Map.take([:table, :column, :tenant])
%{table: "customers", column: "email", tenant: :scope}

@spec list(module()) :: [t()]

Every index declared on a schema, in declaration order.

A module that declares none - or is not a schema at all - has no indexes rather than an error, so a caller sweeping a host's modules does not have to ask twice.

iex> Encryptor.Ecto.BlindIndex.Declaration.list(Encryptor.Ecto.TestSchemas.Customer)
...> |> Enum.map(& &1.column)
[:email_index, :email_short_index, :phone_index]

iex> Encryptor.Ecto.BlindIndex.Declaration.list(Encryptor.Ecto.TestSchemas.Card)
[]

@spec list(module(), atom()) :: [t()]

Every index declared over one source field.

iex> Encryptor.Ecto.BlindIndex.Declaration.list(
...>   Encryptor.Ecto.TestSchemas.Customer, :email)
...> |> Enum.map(& &1.name)
["email_index", "email_short_index"]

@spec new!(module(), term(), term(), term()) :: t()

Builds one declaration, checking its options where the host wrote them.

iex> Encryptor.Ecto.BlindIndex.Declaration.new!(
...>   MyApp.Customer, :email, :email_index, normalize: :email)
%Encryptor.Ecto.BlindIndex.Declaration{
  schema: MyApp.Customer,
  source: :email,
  column: :email_index,
  name: "email_index",
  scope: :tenant,
  scope_declared?: false,
  normalize: :email,
  bits: 256,
  slow: false,
  version: 1
}

:name defaults to the index column's name, not the source field's. Decision 6 tables the default as "the column name" and the record uses "column" for both, so the reading is chosen here: index_name exists to distinguish two indexes over one source column (decision 2), and a default taken from the source would make every index on one field derive the same key - which is the one thing the component is there to prevent. Two indexes over one field are therefore distinct by default, and a host that wants them to share nothing but the field writes nothing extra.

iex> Encryptor.Ecto.BlindIndex.Declaration.new!(
...>   MyApp.Customer, :email, :email_short, bits: 64).name
"email_short"

An unknown option is refused where it is written rather than ignored, and so is a value outside an option's set.

iex> Encryptor.Ecto.BlindIndex.Declaration.new!(
...>   MyApp.Customer, :email, :email_index, normalise: :email)
** (ArgumentError) MyApp.Customer declares blind_index :email, :email_index with unknown options: [:normalise]. Known options: [:name, :scope, :normalize, :bits, :slow, :version].

Every argument but the schema is typed as term/0 rather than as what it has to be. This is the boundary the macro hands a host's literal words across, and a spec that promised they were already an atom and a keyword list would make the checks below unreachable to a static analyser and, worse, imply they had been made somewhere else.

@spec normalize!(t(), binary()) :: binary()

Normalizes one value under this declaration's normalizer.

The declared table and column reach the failure from the encrypted field, so a host normalizer that misbehaves produces an exception naming the schema line rather than the call site.

iex> Encryptor.Ecto.BlindIndex.Declaration.fetch!(
...>   Encryptor.Ecto.TestSchemas.Customer, :email, :email_index)
...> |> Encryptor.Ecto.BlindIndex.Declaration.normalize!(" Bob@Example.COM ")
"bob@example.com"