Alembic

v2.1.0

Alembic v2.1.0 Alembic.ToParams behaviour

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

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

Types 

converted_by_id_by_type :: %{Resource.type => %{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.

params :: list | map | nil

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

resource_by_id_by_type :: %{Resource.type => %{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

Functions

nested_to_foreign_keys(nested_params, schema_module)

Specs

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!"
    }
  ]
}

Callbacks

to_params(convertable, resource_by_id_by_type)

Specs

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
to_params(convertable, resource_by_id_by_type, converted_by_id_by_type)

Specs

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