defmodule EctoResource do
  @moduledoc """
  EctoResource
  ============
  Eliminate boilerplate involved in defining basic CRUD functions in a Phoenix context or Elixir module.

  When using [Context modules](https://hexdocs.pm/phoenix/contexts.html) in a [Phoenix](https://phoenixframework.org/) application,
  there's a general need to define the standard CRUD functions for a given `Ecto.Schema`. Phoenix context generators will even do this automatically.
  Soon you will notice that there's quite a lot of code involved in CRUD access within your contexts.

  This can become problematic for a few reasons:

  * Boilerplate functions for CRUD access, for every `Ecto.Schema` referenced in that context, introduce more noise than signal. This can obscure the more interesting details of the context.
  * These functions may tend to accumulate drift from the standard API by inviting edits for new use-cases, reducing the usefulness of naming conventions.
  * The burden of locally testing wrapper functions, yields low value for the writing and maintainence investment.

  In short, at best this code is redundant and at worst is a deviant entanglement of modified conventions. All of which amounts to a more-painful development experience. `EctoResource` was created to ease this pain.

  Usage
  -----

  ### Basic usage - generate all `EctoResource` functions

  ```elixir
  defmodule MyApp.MyContext do
  alias MyApp.Repo
  alias MyApp.Schema
  use EctoResource

  using_repo(Repo) do
    resource(Schema)
  end
  end
  ```

  This generates all the functions `EctoResource` has to offer:

  * `MyContext.all_schemas/1`
  * `MyContext.change_schema/1`
  * `MyContext.create_schema/1`
  * `MyContext.create_schema!/1`
  * `MyContext.delete_schema/1`
  * `MyContext.delete_schema!/1`
  * `MyContext.get_schema/2`
  * `MyContext.get_schema!/2`
  * `MyContext.get_schema_by/2`
  * `MyContext.get_schema_by!/2`
  * `MyContext.update_schema/2`
  * `MyContext.update_schema!/2`

  ### Explicit usage - generate only given functions

  ```elixir
  defmodule MyApp.MyContext do
  alias MyApp.Repo
  alias MyApp.Schema
  use EctoResource

  using_repo(Repo) do
    resource(Schema, only: [:create, :delete!])
  end
  end
  ```

  This generates only the given functions:

  * `MyContext.create_schema/1`
  * `MyContext.delete_schema!/1`

  ### Exclusive usage - generate all but the given functions

  ```elixir
  defmodule MyApp.MyContext do
  alias MyApp.Repo
  alias MyApp.Schema
  use EctoResource

  using_repo(Repo) do
    resource(Schema, except: [:create, :delete!])
  end
  end
  ```

  This generates all the functions excluding the given functions:

  * `MyContext.all_schemas/1`
  * `MyContext.change_schema/1`
  * `MyContext.create_schema!/1`
  * `MyContext.delete_schema/1`
  * `MyContext.get_schema/2`
  * `MyContext.get_schema_by/2`
  * `MyContext.get_schema_by!/2`
  * `MyContext.get_schema!/2`
  * `MyContext.update_schema/2`
  * `MyContext.update_schema!/2`

  ### Alias `:read` - generate data access functions

  ```elixir
  defmodule MyApp.MyContext do
  alias MyApp.Repo
  alias MyApp.Schema
  use EctoResource

  using_repo(Repo) do
    resource(Schema, :read)
  end
  end
  ```

  This generates all the functions necessary for reading data:

  * `MyContext.all_schemas/1`
  * `MyContext.get_schema/2`
  * `MyContext.get_schema!/2`

  ### Alias `:read_write` - generate data access and manipulation functions, excluding delete

  ```elixir
  defmodule MyApp.MyContext do
  alias MyApp.Repo
  alias MyApp.Schema
  use EctoResource

  using_repo(Repo) do
    resource(Schema, :read_write)
  end
  end
  ```

  This generates all the functions except `delete_schema/1` and `delete_schema!/1`:

  * `MyContext.all_schemas/1`
  * `MyContext.change_schema/1`
  * `MyContext.create_schema/1`
  * `MyContext.create_schema!/1`
  * `MyContext.get_schema/2`
  * `MyContext.get_schema!/2`
  * `MyContext.update_schema/2`
  * `MyContext.update_schema!/2`

  ### Resource functions

  The general idea of the generated resource functions is to abstract away the `Ecto.Repo` and `Ecto.Schema` parts of data access with `Ecto` and provide an API to the context that feels natural and clear to the caller.

  The following examples will all assume a repo named `Repo` and a schema named `Person`.

  #### all_people

  Fetches a list of all %Person{} entries from the data store. _Note: `EctoResource` will pluralize this function name using `Inflex`_

  ```elixir
  iex> all_people()
  [%Person{id: 1}]

  iex> all_people(preloads: [:address])
  [%Person{id: 1, address: %Address{}}]

  iex> all_people(order_by: [desc: :id])
  [%Person{id: 2}, %Person{id: 1}]

  iex> all_people(preloads: [:address], order_by: [desc: :id]))
  [
  %Person{
    id: 2,
    address: %Address{}
  },
  %Person{
    id: 1,
    address: %Address{}
  }
  ]

  iex> all_people(where: [id: 2])
  [%Person{id: 2, address: %Address{}}]
  ```

  #### change_person

  Creates a `%Person{}` changeset.

  ```elixir
  iex> change_person(%{name: "Example Person"})
  #Ecto.Changeset<
  action: nil,
  changes: %{name: "Example Person"},
  errors: [],
  data: #Person<>,
  valid?: true
  >
  ```

  #### create_person

  Inserts a `%Person{}` with the given attributes in the data store, returning an `:ok`/`:error` tuple.

  ```elixir
  iex> create_person(%{name: "Example Person"})
  {:ok, %Person{id: 123, name: "Example Person"}}

  iex> create_person(%{invalid: "invalid"})
  {:error, %Ecto.Changeset}
  ```

  #### create_person!

  Inserts a `%Person{}` with the given attributes in the data store, returning a `%Person{}` or raises `Ecto.InvalidChangesetError`.

  ```elixir
  iex> create_person!(%{name: "Example Person"})
  %Person{id: 123, name: "Example Person"}

  iex> create_person!(%{invalid: "invalid"})
  ** (Ecto.InvalidChangesetError)
  ```

  #### delete_person

  Deletes a given `%Person{}` from the data store, returning an `:ok`/`:error` tuple.

  ```elixir
  iex> delete_person(%Person{id: 1})
  {:ok, %Person{id: 1}}

  iex> delete_person(%Person{id: 999})
  {:error, %Ecto.Changeset}
  ```

  #### delete_person!

  Deletes a given `%Person{}` from the data store, returning the deleted `%Person{}`, or raises `Ecto.StaleEntryError`.

  ```elixir
  iex> delete_person!(%Person{id: 1})
  %Person{id: 1}

  iex> delete_person!(%Person{id: 999})
  ** (Ecto.StaleEntryError)
  ```

  #### get_person

  Fetches a single `%Person{}` from the data store where the primary key matches the given id, returns a `%Person{}` or `nil`.

  ```elixir
  iex> get_person(1)
  %Person{id: 1}

  iex> get_person(999)
  nil

  iex> get_person(1, preloads: [:address])
  %Person{
    id: 1,
    address: %Address{}
  }
  ```

  #### get_person!

  Fetches a single `%Person{}` from the data store where the primary key matches the given id, returns a `%Person{}` or raises `Ecto.NoResultsError`.

  ```elixir
  iex> get_person!(1)
  %Person{id: 1}

  iex> get_person!(999)
  ** (Ecto.NoResultsError)

  iex> get_person!(1, preloads: [:address])
  %Person{
    id: 1,
    address: %Address{}
  }
  ```

  #### get_person_by

  Fetches a single `%Person{}` from the data store where the attributes match the
  given values.

  ```elixir
  iex> get_person_by(%{name: "Chuck Norris"})
  %Person{name: "Chuck Norris"}

  iex> get_person_by(%{name: "Doesn't Exist"})
  nil
  ```

  #### get_person_by!

  Fetches a single `%Person{}` from the data store where the attributes match the
  given values. Raises an `Ecto.NoResultsError` if the record does not exist

  ```elixir
  iex> get_person_by!(%{name: "Chuck Norris"})
  %Person{name: "Chuck Norris"}

  iex> get_person_by!(%{name: "Doesn't Exist"})
  ** (Ecto.NoResultsError)
  ```

  #### update_person

  Updates a given %Person{} with the given attributes, returns an `:ok`/`:error` tuple.

  ```elixir
  iex> update_person(%Person{id: 1}, %{name: "New Person"})
  {:ok, %Person{id: 1, name: "New Person"}}

  iex> update_person(%Person{id: 1}, %{invalid: "invalid"})
  {:error, %Ecto.Changeset}
  ```

  #### update_person!

  Updates a given %Person{} with the given attributes, returns a %Person{} or raises `Ecto.InvalidChangesetError`.

  ```elixir
  iex> update_person!(%Person{id: 1}, %{name: "New Person"})
  %Person{id: 1, name: "New Person"}

  iex> update_person!(%Person{id: 1}, %{invalid: "invalid"})
  ** (Ecto.InvalidChangesetError)
  ```

  Caveats
  -------
  This is not meant to be used as a wrapper for all the Repo functions within a context. Not all callbacks defined in Ecto.Repo are generated. `EctoResource` should be used to help reduce boilerplate code and tests for general CRUD operations.

  It may be the case that `EctoResource` needs to evolve and provide slightly more functionality/flexibility in the future. However, the general focus is reducing boilerplate code.
  """

  alias __MODULE__
  alias EctoResource.Helpers
  alias EctoResource.OptionParser
  alias EctoResource.ResourceFunctions

  @doc """
  Macro to import `EctoResource.using_repo/2`

  ## Examples
      use EctoResource
  """
  defmacro __using__(_) do
    quote do
      import EctoResource, only: [using_repo: 2]
    end
  end

  @doc """
  Macro to define schema access within a given `Ecto.Repo`

  ## Examples
      using_repo(Repo) do
        resource(Schema)
      end
  """
  defmacro using_repo(repo, do: block) do
    quote do
      Module.register_attribute(__MODULE__, :repo, [])
      Module.put_attribute(__MODULE__, :repo, unquote(repo))
      Module.register_attribute(__MODULE__, :resources, accumulate: true)
      import EctoResource, only: [resource: 2, resource: 1]
      unquote(block)
      def __resource__(:resources), do: @resources
      Module.delete_attribute(__MODULE__, :resources)
      Module.delete_attribute(__MODULE__, :repo)
    end
  end

  @doc """
  Macro to define CRUD methods for the given `Ecto.Repo` in the using module.

  ## Examples
      using(Repo) do
        resource(Schema)
      end

      using(Repo) do
        resource(Schema, suffix: false)
      end

      using(Repo) do
        resource(Schema, only: [:get])
      end

      using(Repo) do
        resource(Schema, except: [:delete])
      end

      using(Repo) do
        resource(Schema, :read)
      end

      using(Repo) do
        resource(Schema, :write)
      end

      using(Repo) do
        resource(Schema, :delete)
      end
  """
  # credo:disable-for-next-line
  defmacro resource(schema, options \\ []) do
    # credo:disable-for-next-line
    quote bind_quoted: [schema: schema, options: options] do
      suffix = OptionParser.create_suffix(schema, options)
      schema_name = Helpers.schema_name(schema)
      resources = OptionParser.parse(suffix, options)
      descriptions = Helpers.resource_descriptions(resources)

      Module.put_attribute(__MODULE__, :resources, {@repo, schema, descriptions})

      Enum.each(resources, fn {action, %{name: name}} ->
        case action do
          :all ->
            @doc """
            Fetches all #{schema_name} entries from the data store.

            ## Examples
                #{name}()
                [%#{schema_name}{id: 123}]

                #{name}(preloads: [:relation])
                [%#{schema_name}{id: 123, relation: %Relation{}}]

                #{name}(order_by: [desc: :id])
                [%#{schema_name}{id: 2}, %#{schema_name}{id: 1}]

                #{name}(preloads: [:relation], order_by: [desc: :id])
                [
                  %#{schema_name}{
                    id: 2,
                    relation: %Relation{}
                  },
                  %#{schema_name}{
                    id: 1,
                    relation: %Relation{}
                  }
                ]
            """
            @spec unquote(name)(keyword(list())) :: list(Ecto.Schema.t())
            def unquote(name)(options \\ []) do
              ResourceFunctions.all(@repo, unquote(schema), options)
            end

          :change ->
            @doc """
            Creates a #{schema_name} changeset from an existing schema struct.

                #{name}(%#{schema_name}{}, %{})

                #Ecto.Changeset<
                  action: nil,
                  changes: %{},
                  errors: [],
                  data: ##{schema_name}<>,
                  valid?: true
                >

                #{name}(%#{schema_name}{}, [])

                #Ecto.Changeset<
                  action: nil,
                  changes: %{},
                  errors: [],
                  data: ##{schema_name}<>,
                  valid?: true
                >

            """
            @spec unquote(name)(Ecto.Schema.t(), map() | Keyword.t()) :: Ecto.Changeset.t()
            def unquote(name)(changeable, changes) do
              ResourceFunctions.change(unquote(schema), changeable, changes)
            end

          :changeset ->
            @doc """
            Creates a blank changeset.

                changeset()

                #Ecto.Changeset<
                  action: nil,
                  changes: %{},
                  errors: [],
                  data: ##{schema_name}<>,
                  valid?: true
                >
            """
            @spec unquote(name)() :: Ecto.Changeset.t()
            def unquote(name)() do
              ResourceFunctions.changeset(unquote(schema))
            end

          :create ->
            @doc """
            Inserts a #{schema_name} with the given attributes in the data store.

            ## Examples
                #{name}(%{})
                {:ok, %#{schema_name}{}}

                #{name}([])
                {:ok, %#{schema_name}{}}

                #{name}(%{invalid: "invalid"})
                  {:error, %Ecto.Changeset{}}
            """
            @spec unquote(name)(map() | Keyword.t()) ::
                    {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}
            def unquote(name)(attributes) do
              ResourceFunctions.create(@repo, unquote(schema), attributes)
            end

          :create! ->
            @doc """
            Same as create_#{suffix}/1 but returns the struct or raises if the changeset is invalid.

            ## Examples
                #{name}(%{})
                %#{schema_name}{}

                #{name}([])
                %#{schema_name}{}

                #{name}(%{invalid: "invalid"})
                ** (Ecto.InvalidChangesetError)
            """
            @spec unquote(name)(map() | Keyword.t()) ::
                    Ecto.Schema.t() | Ecto.InvalidChangesetError
            def unquote(name)(attributes) do
              ResourceFunctions.create!(@repo, unquote(schema), attributes)
            end

          :delete ->
            @doc """
            Deletes a given %#{schema_name}{} from the data store.

            ## Examples
                #{name}(%#{schema_name}{id: 123})
                {:ok, %#{schema_name}{id: 123}}

                #{name}(%#{schema_name}{id: 456})
                {:error, %Ecto.Changeset{}}

            """
            @spec unquote(name)(Ecto.Schema.t()) ::
                    {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}
            def unquote(name)(struct) do
              ResourceFunctions.delete(@repo, struct)
            end

          :delete! ->
            @doc """
            Same as delete_#{suffix}/1 but returns the struct or raises if the changeset is invalid.

            ## Examples
                #{name}(%#{schema_name}{id: 123})
                %#{schema_name}{id: 123}

                #{name}(%#{schema_name}{id: 456})
                ** (Ecto.StaleEntryError)
            """
            def unquote(name)(struct) do
              ResourceFunctions.delete!(@repo, struct)
            end

          :get ->
            @doc """
            Fetches a single #{schema_name} from the data store where the primary key matches the given id.

            ## Examples
                #{name}(123)
                %#{schema_name}{id: 123}

                #{name}(456)
                nil

                #{name}(123, preloads: [:relation])
                %#{schema_name}{
                  id: 1,
                  relation: %Relation{}
                }
            """
            @spec unquote(name)(String.t() | integer(), keyword(list())) :: Ecto.Schema.t() | nil
            def unquote(name)(id, options \\ []) do
              ResourceFunctions.get(@repo, unquote(schema), id, options)
            end

          :get! ->
            @doc """
            Same as get_#{suffix}/2 but raises Ecto.NoResultsError if no record was found.

            ## Examples
                #{name}(123)
                %#{schema_name}{id: 123}

                #{name}(456)
                ** (Ecto.NoResultsError)

                #{name}(123, preloads: [:relation])
                %#{schema_name}{
                  id: 1,
                  relation: %Relation{}
                }
            """
            def unquote(name)(id, options \\ []) do
              ResourceFunctions.get!(@repo, unquote(schema), id, options)
            end

          :get_by ->
            @doc """
            Fetches a single result from the query.

            Returns nil if no result was found. Raises if more than one entry.

            ## Examples
                #{name}(name: "Some Name")
                %#{schema_name}{name: "Some Name"}

                #{name}(%{name: "Some Name"})
                %#{schema_name}{name: "Some Name"}

                #{name}(name: "Missing")
                nil
            """
            def unquote(name)(attributes, options \\ []) do
              ResourceFunctions.get_by(@repo, unquote(schema), attributes, options)
            end

          :get_by! ->
            @doc """
            Similar to get_by/2 but raises Ecto.NoResultsError if no record was found.

            Raises if more than one entry.

            ## Examples
                #{name}(name: "Some Name")
                %#{schema_name}{name: "Some Name"}

                #{name}(%{name: "Some Name"})
                %#{schema_name}{name: "Some Name"}

                #{name}(name: "Missing")
                ** (Ecto.NoResultsError)
            """
            def unquote(name)(attributes, options \\ []) do
              ResourceFunctions.get_by!(@repo, unquote(schema), attributes, options)
            end

          :update ->
            @doc """
            Updates a %#{schema_name}{} with the given attributes.

            ## Examples
                #{name}(%#{schema_name}{id: 123}, %{attribute: "updated attribute"})
                {:ok, %#{schema_name}{id: 123, attribute: "updated attribute"}}

                #{name}(%#{schema_name}{id: 123}, attribute: "updated attribute")
                {:ok, %#{schema_name}{id: 123, attribute: "updated attribute"}}

                #{name}(%#{schema_name}{id: 123}, %{}, force: true)
                {:ok, %#{schema_name}{id: 123, attribute: "updated attribute"}}

                #{name}(%#{schema_name}{id: 123}, %{}, prefix: "my_prefix")
                {:ok, %#{schema_name}{id: 123, attribute: "updated attribute"}}

                #{name}(%#{schema_name}{id: 123}, %{invalid: "invalid"})
                {:error, %Ecto.Changeset{}}
            """
            @spec unquote(name)(Ecto.Schema.t(), map() | Keyword.t()) ::
                    {:ok, Ecto.Schema.t()} | {:error, Ecto.Changeset.t()}
            def unquote(name)(struct, attributes) do
              ResourceFunctions.update(@repo, unquote(schema), struct, attributes)
            end

            @doc """
            Same as update_#{suffix}/2 returns a %#{schema_name}{} or raises if the changeset is invalid.

            ## Examples
                #{name}(%#{schema_name}{id: 123}, %{attribute: "updated attribute"})
                %#{schema_name}{id: 123, attribute: "updated attribute"}

                #{name}(%#{schema_name}{id: 123}, %{}, force: true)
                %#{schema_name}{id: 123, attribute: "updated attribute"}

                #{name}(%#{schema_name}{id: 123}, %{}, prefix: "my_prefix")
                %#{schema_name}{id: 123, attribute: "updated attribute"}

                #{name}(%#{schema_name}{id: 123}, %{invalid: "invalid"})
                ** (Ecto.InvalidChangesetError)
            """

          :update! ->
            @spec unquote(name)(Ecto.Schema.t(), map() | Keyword.t()) ::
                    Ecto.Schema.t() | Ecto.InvalidChangesetError
            def unquote(name)(struct, attributes) do
              ResourceFunctions.update!(@repo, unquote(schema), struct, attributes)
            end

          _ ->
            nil
        end
      end)
    end
  end
end