diff --git a/CHANGELOG.md b/CHANGELOG.md index 871f66e..c146eb7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,11 +1,13 @@ ## Changelog +#### v2.5.0 +- add support for abstract schemas / polymorphic associations + #### V2.4.0 - add recursive relational filtering - add `%{field: %{!=: [1, 2, 3]}}` to allow `NOT IN ANY` queries - fix intermittent failure from `function_exported?(schema, :create_changeset, 1)` - #### V2.3.0 - add ability to optionally require a id or a cast/put assoc - type spec fixes diff --git a/lib/ecto_shorts.ex b/lib/ecto_shorts.ex index 9c755a0..6de1241 100644 --- a/lib/ecto_shorts.ex +++ b/lib/ecto_shorts.ex @@ -19,7 +19,7 @@ defmodule EctoShorts do build Ecto queries with parameters. In other words, you can turn data into a query without having to write one. - ## EctoShorts.Actions + ## Actions `EctoShorts.Actions` allows you to use the `Ecto.Repo` api without having the do any of the pre-requisite setup as it @@ -79,19 +79,11 @@ defmodule EctoShorts do ``` All actions can accept an optional argument of a keyword list - that can be used to configure which Repo the action should use. + that can be used to configure which `repo` the action should use. - ## Options + See the `EctoShorts.Actions` module documentation for more information. - * `:replica` - A module that uses Ecto.Repo. If you don't - want to perform any reads against your primary, you can - specify a replica to read from. This option takes - precedence over the :repo option and will be used if set. - - * `:repo` - A module that uses Ecto.Repo. This is - commonly your primary repository. - - ## EctoShorts.CommonFilters + ## Common Filters CommonFilters allows you build queries from data instead of writing your own queries. For example, where you would @@ -120,7 +112,7 @@ defmodule EctoShorts do See `EctoShorts.CommonFilters` for more info on information on the available filters. - ## EctoShorts.CommonChanges + ## Common Changes `EctoShorts.CommonChanges` is responsible for updating relations on schemas. It allows you to update associations @@ -209,22 +201,10 @@ defmodule EctoShorts do `source` and `schema` for the operation in a tuple: ``` - {"comments", Comment} - ``` - - For example: - - ``` - EctoShorts.Actions.all({"source", YourSchema}) - ``` - - or - - ``` - EctoShorts.CommonFilters.convert_params_to_filter({"source", YourSchema}, %{name: "example.txt"}) + YourRepo.all({"source", YourSchema}) ``` - The abstract schema syntax can be used with: + The syntax can be used with any function in the modules: * `EctoShorts.Actions` * `EctoShorts.CommonFilters` diff --git a/lib/ecto_shorts/actions.ex b/lib/ecto_shorts/actions.ex index 306ad4d..e84822b 100644 --- a/lib/ecto_shorts/actions.ex +++ b/lib/ecto_shorts/actions.ex @@ -31,22 +31,50 @@ defmodule EctoShorts.Actions do You can read more on reusable ecto code [here](https://learn-elixir.dev/blogs/creating-reusable-ecto-code) - ### Supporting multiple Repos + ### Multiple Repos - To support multiple repos, what we can do is pass arguments to the last parameter - of most `EctoShorts.Actions` calls - - #### Example + The `repo` used the functions in this module can + be configured by passing in the option `:repo` or + `:replica` during the function call: ```elixir defmodule MyApp.Accounts do alias EctoShorts.Actions alias MyApp.Accounts.User - def all_users(params), do: Actions.all(User, params, replica: MyApp.Repo.Replica) - def create_user(params), do: Actions.find(User, params, repo: MyApp.Repo) + def all_users(params) do + Actions.all(User, params, replica: MyApp.Repo.Replica) + end + + def create_user(params) do + Actions.find(User, params, repo: MyApp.Repo) + end end ``` + + ## Shared Options + + Almost of the functions outlined in this module accept the following options: + + * `:replica` - A module that uses Ecto.Repo. If you don't + want to perform any reads against your primary, you can + specify a replica to read from. This option takes + precedence over the :repo option and will be used if set. + + * `:repo` - A module that uses Ecto.Repo. This is + commonly your primary repository. + + * `:changeset` - Allows you to build or modify the final + changeset before executing a repo operation using a + function. The can be one of the following: + + * `2-arity` function - This is invoked with the schema + data and params (eg. `fun.(schema_data, params)`) and + must return an `Ecto.Changeset`. + + * `1-arity` function - This is invoked with the + changeset (eg. `fun.(changeset)`) and must return an + `Ecto.Changeset`. """ @type id :: binary() | integer() @type source :: binary() @@ -77,10 +105,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.get/3](https://hexdocs.pm/ecto/Ecto.Repo.html#c:get/3) for more options. @@ -106,6 +131,10 @@ defmodule EctoShorts.Actions do @doc """ Fetches all records matching the given query. + ### Options + + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. + See [Ecto.Repo.all/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:all/2) for more options. ### Examples @@ -130,10 +159,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.all/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:all/2) for more options. @@ -179,13 +205,10 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used if set. - - * `:repo` - A module that uses `Ecto.Repo`. - * `:order_by` - Orders the fields based on one or more fields. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. + See [Ecto.Repo.all/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:all/2) for more options. ## Examples @@ -220,10 +243,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.all/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:one/2) for more options. @@ -279,7 +299,7 @@ defmodule EctoShorts.Actions do ### Options - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.insert/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:insert/2) for more options. @@ -311,11 +331,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See `find/3` and `create/3` for more information. @@ -353,11 +369,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See `find/3` and `update/4` for more information. @@ -393,11 +405,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See `find/3`, `create/3` and `update/4` for more information. @@ -440,11 +448,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See `update/4` and [Ecto.Repo.get/3](https://hexdocs.pm/ecto/Ecto.Repo.html#c:get/3) for more options. @@ -532,7 +536,7 @@ defmodule EctoShorts.Actions do ### Options - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.delete/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:delete/2) for more options. @@ -592,11 +596,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See `find/3` and [Ecto.Repo.delete/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:delete/2) for more options. @@ -625,11 +625,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.stream/2](https://hexdocs.pm/ecto/Ecto.Repo.html#c:stream/2) for more options. @@ -663,11 +659,7 @@ defmodule EctoShorts.Actions do ### Options - * `:replica` - A module that uses `Ecto.Repo`. This option takes - precedence over the `:repo` option and will be used to - fetch the record if set. - - * `:repo` - A module that uses `Ecto.Repo`. + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. See [Ecto.Repo.aggregate/4](https://hexdocs.pm/ecto/Ecto.Repo.html#c:aggregate/4) for more options. @@ -706,11 +698,12 @@ defmodule EctoShorts.Actions do ***Note: Relational filtering doesn't work on this function*** - ## Options - * `:repo` - A module that uses the Ecto.Repo Module. - * `:replica` - If you don't want to perform any reads against your Primary, you can specify a replica to read from. + ### Options + + See the ["Shared options"](#module-shared-options) section at the module documentation for remaining options. + + ### Examples - ## Examples iex> {:ok, records} = EctoSchemas.Actions.find_or_create_many(EctoSchemas.Accounts.User, [%{name: "foo"}, %{name: "bar}]) iex> length(records) === 2 """