Behavior for implementing custom database type handlers.

When you have custom database types (enums, domains, composite types), implement this behavior to teach Lotus how to cast values for that type.

Example: Custom Enum Type

defmodule MyApp.StatusEnumHandler do
  @behaviour Lotus.Storage.TypeHandler

  @valid_values ~w(active inactive pending archived)

  @impl true
  def cast(value, _opts) when value in @valid_values do
    {:ok, value}
  end

  def cast(value, _opts) when is_binary(value) do
    valid_values = ~w(active inactive pending archived)
    if String.downcase(value) in valid_values do
      {:ok, String.downcase(value)}
    else
      {:error, "Invalid status: must be one of #{inspect(valid_values)}"}
    end
  end

  def cast(_value, _opts) do
    {:error, "Status must be a string"}
  end

  @impl true
  def requires_casting?(_value), do: false  # Let database validate
end

Registration

Register your handler in config/config.exs:

config :lotus, :type_handlers, %{
  "status_enum" => MyApp.StatusEnumHandler,
  "my_custom_domain" => MyApp.CustomDomainHandler
}

The key should match the exact database type name from information_schema.columns.data_type.

Example: UUID v7 Custom Handler

defmodule MyApp.UUIDv7Handler do
  @behaviour Lotus.Storage.TypeHandler

  @impl true
  def cast(value, _opts) do
    case Unid.UUID.cast(value) do  # Using Unid library
      {:ok, uuid_string} ->
        case Unid.UUID.dump(uuid_string) do
          {:ok, binary} -> {:ok, binary}
          :error -> {:error, "Invalid UUID v7 format"}
        end
      :error ->
        {:error, "Invalid UUID v7"}
    end
  end

  @impl true
  def requires_casting?(_value), do: true  # Always cast to binary
end

Example: PostgreSQL Composite Type

defmodule MyApp.AddressHandler do
  @behaviour Lotus.Storage.TypeHandler

  @impl true
  def cast(value, _opts) when is_map(value) do
    # Validate required fields
    if Map.has_key?(value, "street") and Map.has_key?(value, "city") do
      {:ok, value}
    else
      {:error, "Address must have street and city fields"}
    end
  end

  def cast(value, _opts) when is_binary(value) do
    case Lotus.JSON.decode(value) do
      {:ok, map} when is_map(map) -> cast(map, %{})
      _ -> {:error, "Invalid JSON for address"}
    end
  rescue
    _ -> {:error, "Invalid address format"}
  end

  def cast(_value, _opts) do
    {:error, "Address must be a map or JSON string"}
  end

  @impl true
  def requires_casting?(_value), do: true
end