Alembic

v4.0.0

Alembic v4.0.0 Alembic.ToParams behaviour View Source

The Alembic.ToParams behaviour converts a data structure in the Alembic namespace to the params format used by Ecto.Changeset.cast/4.

Link to this section Summary

Types

converted_by_id_by_type()

A nested map with the outer layer keyed by the Alembic.Resource.type, then the next layer keys by the Alembic.Resource.id with the values not being present initially, but being updated to true once the {type, id} is converted once

params()

Params format used by Ecto.Changeset.cast/4

resource_by_id_by_type()

A nest map with the outer layer keyed by the Alembic.Resource.type, then the next layer keyed by the Alembic.Resource.id with the values being the full Alembic.Resource.t

Functions

nested_to_foreign_keys(nested_params, schema_module)

Converts nested parameters for belongs_to associations to a foreign key parameter

Callbacks

to_params(convertable, resource_by_id_by_type)

Parameters

to_params(convertable, resource_by_id_by_type, converted_by_id_by_type)

Unlike to_params/2, if type and id of convertable already exists in converted_by_id_by_type, then the params returned are only %{ "id" => id } without any further expansion, that is, a resource identifier, so that loops are prevented

Link to this section Types

Link to this type converted_by_id_by_type() View Source 
converted_by_id_by_type() :: %{
  optional(Resource.type()) => %{optional(Resource.id()) => boolean()}
}

A nested map with the outer layer keyed by the Alembic.Resource.type, then the next layer keys by the Alembic.Resource.id with the values not being present initially, but being updated to true once the {type, id} is converted once.

Link to this type params() View Source 
params() :: list() | map() | nil

Params format used by Ecto.Changeset.cast/4.

Link to this type resource_by_id_by_type() View Source 
resource_by_id_by_type() :: %{
  optional(Resource.type()) => %{optional(Resource.id()) => Resource.t()}
}

A nest map with the outer layer keyed by the Alembic.Resource.type, then the next layer keyed by the Alembic.Resource.id with the values being the full Alembic.Resource.t

Link to this section Functions

Link to this function nested_to_foreign_keys(nested_params, schema_module) View Source 
nested_to_foreign_keys(params(), module()) :: params()

Converts nested parameters for belongs_to associations to a foreign key parameter.

iex> Alembic.ToParams.nested_to_foreign_keys(
...>   %{
...>     "id" => 1,
...>     "author" => %{
...>       "id" => 2
...>     },
...>     "text" => "Welcome to my new blog!"
...>   },
...>   Alembic.TestPost
...> )
%{
  "id" => 1,
  "author_id" => 2,
  "text" => "Welcome to my new blog!"
}

nil for the nested parameters converts to a nil foreign key parameter

iex> Alembic.ToParams.nested_to_foreign_keys(
...>   %{
...>     "id" => 1,
...>     "author" => nil,
...>     "text" => "Welcome to my new blog!"
...>   },
...>   Alembic.TestPost
...> )
%{
  "id" => 1,
  "author_id" => nil,
  "text" => "Welcome to my new blog!"
}

This differs from when the nested parameters are not even present, in which case the foreign key won’t be added

iex> Alembic.ToParams.nested_to_foreign_keys(
...>   %{
...>     "id" => 1,
...>     "text" => "Welcome to my new blog!"
...>   },
...>   Alembic.TestPost
...> )
%{
  "id" => 1,
  "text" => "Welcome to my new blog!"
}

From the other side of the belongs_to, the has_many nested params are unchanged

iex> Alembic.ToParams.nested_to_foreign_keys(
...>   %{
...>     "id" => 2,
...>     "name" => "Alice",
...>     "posts" => [
...>       %{
...>         "id" => 1,
...>         "text" => "Welcome to my new blog!"
...>       }
...>     ]
...>   },
...>   Alembic.TestAuthor
...> )
%{
  "id" => 2,
  "name" => "Alice",
  "posts" => [
    %{
      "id" => 1,
      "text" => "Welcome to my new blog!"
    }
  ]
}

Link to this section Callbacks

Link to this callback to_params(convertable, resource_by_id_by_type) View Source 
to_params(convertable :: any(), resource_by_id_by_type()) ::
  params() | {:error, :unset}

Parameters

  • convertable - an Alembic.Document.t hierarchy data structure
  • resources_by_id_by_type - A nest map with the outer layer keyed by the Alembic.Resource.type, then the next layer keyed by the Alembic.Resource.id with the values being the full Alembic.Resource.t from Alembic.Document.t included.

Returns

Success

  • nil if an empty singleton
  • %{} - if a non-empty singleton
  • [] - if an empty collection
  • [%{}] - if a non-empty collection

Errors

  • {:error, :unset} - if the convertable data is not set
Link to this callback to_params(convertable, resource_by_id_by_type, converted_by_id_by_type) View Source 
to_params(
  convertable :: any(),
  resource_by_id_by_type(),
  converted_by_id_by_type()
) :: params() | {:error, :already_converted | :unset}

Unlike to_params/2, if type and id of convertable already exists in converted_by_id_by_type, then the params returned are only %{ "id" => id } without any further expansion, that is, a resource identifier, so that loops are prevented.

Parameters

  • convertable - an Alembic.Document.t hierarchy data structure
  • resources_by_id_by_type - A nest map with the outer layer keyed by the Alembic.Resource.type, then the next layer keyed by the Alembic.Resource.id with the values being the full Alembic.Resource.t from Alembic.Document.t included.
  • converted_by_id_by_type - Tracks which (type, id) have been converted already to prevent infinite recursion when expanding indirect relationships.

Returns

Success

  • {nil} if an empty singleton
  • %{} - if a non-empty singleton
  • [] - if an empty collection
  • [%{}] - if a non-empty collection

Errors

  • {:error, :already_converted} - if the type and id of convertable already exists in converted_by_id_by_type
  • {:error, :unset} - if the convertable data is not set