defmodule EctoUnixTimestamp do
  @moduledoc """
  An Ecto type for datetime fields that are cast as **Unix timestamps**.

  This type is useful when the data you're casting comes in as a Unix timestamp. In those
  cases, the built-in Ecto types `:utc_datetime`, `:utc_datetime_usec`, `:naive_datetime`,
  and `:naive_datetime_usec` work for *storing* the data but not for *casting*. You're forced
  to pre-parse the parameters that contain the Unix timestamps and convert them into
  `DateTime` or `NaiveDateTime` structs before passing them to Ecto, which somewhat defeats
  the purpose of Ecto casting for those fields. This nimble library solves exactly this issue.

  > #### Casting Datetimes {: .info}
  >
  > When casting a field of type `EctoUnixTimestamp`, the value of the field can also be a
  > `DateTime` or `NaiveDateTime` struct. In that case, the value is passed through as-is.

  ## Usage

  Use this Ecto type in your schemas. You'll have to choose the **precision** of the Unix
  timestamp, and the underlying database data type you want to *store* the data as.

      defmodule User do
        use Ecto.Schema

        schema "users" do
          field :created_at, EctoUnixTimestamp, unit: :second, underlying_type: :utc_datetime
        end
      end

  Once you have this, you can cast Unix timestamps:

      import Ecto.Changeset

      changeset = cast(%User{}, %{created_at: 1672563600}, [:created_at])

      fetch_field!(changeset, :created_at)
      #=> ~U[2023-01-01 09:00:00Z]

  ## Options

  A `field` whose type is `EctoUnixTimestamp` accepts the following options:

    * `:unit` - The precision of the Unix timestamp. Must be one of `:second`,
      `:millisecond`, `:microsecond`, or `:nanosecond`. This option is **required**.

    * `:underlying_type` - The underlying Ecto type to use for storing the data.
      This option is **required**. It can be one of the native datetime types, that is,
      `:utc_datetime`, `:utc_datetime_usec`, `:naive_datetime`, or
      `:naive_datetime_usec`.

    * `:accept_strings` - A boolean that indicates whether the type should accept strings
      as input. If `true`, the type will attempt to parse strings as integers. If `false`,
      the type will only accept integers and `DateTime`/`NaiveDateTime` structs. Defaults to
      `true`. *Available since v1.0.0*.

  ## Examples of Casting

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :millisecond, underlying_type: :utc_datetime)
      iex> Ecto.Type.cast(type, 1706818415865)
      {:ok, ~U[2024-02-01 20:13:35.865Z]}

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :second, underlying_type: :naive_datetime)
      iex> Ecto.Type.cast(type, 1706818415)
      {:ok, ~N[2024-02-01 20:13:35Z]}

  With a `DateTime` or `NaiveDateTime` struct:

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :second, underlying_type: :naive_datetime)
      iex> Ecto.Type.cast(type, ~N[2024-02-01 20:13:35Z])
      {:ok, ~N[2024-02-01 20:13:35Z]}

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :second, underlying_type: :utc_datetime_usec)
      iex> Ecto.Type.cast(type, ~U[2024-02-01 20:13:35.846393Z])
      {:ok, ~U[2024-02-01 20:13:35.846393Z]}

  With a string:

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :millisecond, underlying_type: :utc_datetime, accept_strings: true)
      iex> Ecto.Type.cast(type, "1706818415866")
      {:ok, ~U[2024-02-01 20:13:35.866Z]}

  `nil` is always valid, as with any other Ecto type:

      iex> type = Ecto.ParameterizedType.init(EctoUnixTimestamp, unit: :second, underlying_type: :naive_datetime)
      iex> Ecto.Type.cast(type, nil)
      {:ok, nil}

  """

  use Ecto.ParameterizedType

  @typedoc """
  Type for a field of type `EctoUnixTimestamp`.
  """
  @typedoc since: "0.2.0"
  @type t() :: DateTime.t() | NaiveDateTime.t()

  @valid_units [
    :second,
    :millisecond,
    :microsecond,
    :nanosecond
  ]

  @valid_underlying_types [
    :utc_datetime,
    :utc_datetime_usec,
    :naive_datetime,
    :naive_datetime_usec
  ]

  @impl true
  def init(opts) do
    unit =
      Keyword.get_lazy(opts, :unit, fn ->
        raise ArgumentError, "missing required option :unit"
      end)

    underlying_type =
      Keyword.get_lazy(opts, :underlying_type, fn ->
        raise ArgumentError, "missing required option :underlying_type"
      end)

    accept_strings? = Keyword.get(opts, :accept_strings, true)

    if unit not in @valid_units do
      raise ArgumentError, """
      invalid value for the :unit option, expected one of #{inspect(@valid_units)}, \
      got: #{inspect(unit)}
      """
    end

    if underlying_type not in @valid_underlying_types do
      raise ArgumentError, """
      invalid value for the :underlying_type option, expected one of \
      #{inspect(@valid_underlying_types)}, got: #{inspect(underlying_type)}
      """
    end

    if not is_boolean(accept_strings?) do
      raise ArgumentError, """
      invalid value for the :accept_strings option, expected a boolean, got: \
      #{inspect(accept_strings?)}
      """
    end

    %{unit: unit, type: underlying_type, accept_strings?: accept_strings?}
  end

  @impl true
  def type(%{type: type}) do
    type
  end

  @impl true
  def cast(data, params)

  def cast(nil, _params) do
    {:ok, nil}
  end

  def cast(%mod{} = data, %{type: type}) when mod in [DateTime, NaiveDateTime] do
    Ecto.Type.cast(type, data)
  end

  def cast(data, %{unit: unit, type: type}) when is_integer(data) do
    case DateTime.from_unix(data, unit) do
      {:ok, dt} when type in [:naive_datetime, :naive_datetime_usec] ->
        {:ok, DateTime.to_naive(dt)}

      {:ok, dt} ->
        {:ok, dt}

      {:error, _reason} ->
        :error
    end
  end

  def cast(data, %{accept_strings?: true} = params) when is_binary(data) do
    case Integer.parse(data) do
      {int, ""} ->
        cast(int, params)

      _other ->
        error = """
        Unix timestamp must be an integer, a string with a Unix timestamp, or a \
        DateTime/NaiveDateTime struct\
        """

        {:error, [reason: error]}
    end
  end

  def cast(_other, _params) do
    {:error, [reason: "Unix timestamp must be an integer or a DateTime/NaiveDateTime struct"]}
  end

  @impl true
  def load(data, loader, params)
  def load(nil, _loader, _params), do: {:ok, nil}
  def load(value, _loader, %{type: type}), do: Ecto.Type.load(type, value)

  @impl true
  def dump(data, dumper, params)
  def dump(nil, _dumper, _params), do: {:ok, nil}
  def dump(%mod{} = data, _dumper, _params) when mod in [DateTime, NaiveDateTime], do: {:ok, data}
  def dump(_data, _dumper, _params), do: :error
end