FatEcto: Supercharge Your Ecto Queries with Ease! ๐Ÿš€

View Source

Build Status Coverage Status hex.pm version hex.pm downloads hex.pm license Last Updated


Description

FatEcto is an Elixir package designed to make your life easier when working with Ecto. It simplifies query building, filtering, sorting, and paginationโ€”so you can focus on what truly matters: building amazing applications. With FatEcto, writing complex repeating queries becomes effortless, flexible, and powerful! ๐Ÿ’ช


Installation

Add fat_ecto to your list of dependencies in mix.exs:

def deps do
  [
    # Check https://hexdocs.pm/fat_ecto for the latest version
    {:fat_ecto, "~> 1.2"}
  ]
end

Then, run mix deps.get to install the package.


Features & Modules

๐Ÿ›  FatEcto.Query.Dynamics.Buildable โ€“ Dynamic Filtering Made Easy

Tired of writing repetitive query filters? The Whereable module lets you dynamically filter records using flexible conditions passed from your web or mobile clientsโ€”with little to no effort! And the best part? You stay in control. ๐Ÿš€

Usage

defmodule FatEcto.HospitalDynamicsBuilder do
  use FatEcto.Query.Dynamics.Buildable,
    filterable: [
      id: ["$EQUAL", "$NOT_EQUAL"]
    ],
    overrideable: ["name", "phone"],
    ignoreable: [
      name: ["%%", "", [], nil],
      phone: ["%%", "", [], nil]
    ]

  import Ecto.Query

  @impl true
  # You can implement override_buildable for your custom filters
  def override_buildable("name", "$ILIKE", value) do
    dynamic([r], ilike(fragment("(?)::TEXT", r.name), ^value))
  end

  def override_buildable(_field, _operator, _value), do: nil
end

Example Usage

Here are some practical examples of how to use FatEcto.HospitalDynamicsBuilder to dynamically build queries:

Example 1: Basic Filtering by ID
# Filter hospitals with ID equal to 1
params = %{"id" => %{"$EQUAL" => 1}}
dynamics = FatEcto.HospitalDynamicsBuilder.build(params)

# Use the dynamics in a query
import Ecto.Query
query = where(FatEcto.FatHospital, ^dynamics)

# Resulting query:
# from(h in FatEcto.FatHospital, where: h.id == 1)
Example 2: Case-Insensitive Name Search
# Filter hospitals with names containing "St. Mary"
params = %{"name" => %{"$ILIKE" => "%St. Mary%"}}
dynamics = FatEcto.HospitalDynamicsBuilder.build(params)

# Use the dynamics in a query
import Ecto.Query
query = where(FatEcto.FatHospital, ^dynamics)

# Resulting query:
# from(h in FatEcto.FatHospital, where: ilike(fragment("(?)::TEXT", h.name), ^"%St. Mary%"))
Example 3: Combining Multiple Filters
# Filter hospitals with ID not equal to 2 AND name containing "General"
params = %{
  "id" => %{"$NOT_EQUAL" => 2},
  "name" => %{"$ILIKE" => "%General%"}
}
dynamics = FatEcto.HospitalDynamicsBuilder.build(params)

# Use the dynamics in a query
import Ecto.Query
query = where(FatEcto.FatHospital, ^dynamics)

# Resulting query:
# from(h in FatEcto.FatHospital, where: h.id != 2 and ilike(fragment("(?)::TEXT", h.name), ^"%General%"))
Example 4: Ignoring Empty or Invalid Values
# Filter hospitals with a name, but ignore empty or invalid values
params = %{"name" => %{"$ILIKE" => "%%"}}  # Empty value is ignored
dynamics = FatEcto.HospitalDynamicsBuilder.build(params)

# Use the dynamics in a query
import Ecto.Query
query = where(FatEcto.FatHospital, ^dynamics)

# Resulting query:
# from(h in FatEcto.FatHospital)  # No filtering applied for name
Example 5: Even Complex Nested conditions
# Filter hospitals with a name, but ignore empty or invalid values
params = %{
  "$OR" => [
    %{
      "name" => %{"$ILIKE" => "%John%"},
      "$OR" => %{"rating" => %{"$GT" => 18}, "location" => "New York"}
    },
    %{
      "start_date" => "2023-01-01",
      "$AND" => [
        %{"rating" => %{"$GT" => 4}},
        %{"email" => "fat_ecto@example.com"}
      ]
    }
  ]
}

dynamics = DoctorFilter.build(params)

# Resulting dynamic:
dynamic(
  [q],
  ((q.location == ^"New York" or q.rating > ^18) and ilike(fragment("(?)::TEXT", q.name), ^"%John%")) or
    (q.rating > ^4 and q.email == ^"fat_ecto@example.com" and q.start_date == ^"2023-01-01")
)

# You can now apply the result on where just like above examples

๐Ÿ”„ FatEcto.Sort.Sortable โ€“ Effortless Sorting

Sorting should be simpleโ€”and with Sortable, it is! Your frontend can send sorting parameters, and FatEcto will seamlessly generate the right sorting queries, allowing you to build powerful, customizable sorting logic without breaking a sweat. ๐Ÿ˜Ž

Usage of FatSortable

defmodule Fat.SortQuery do
  import Ecto.Query
  use FatEcto.Sort.Sortable,
    sortable: [id: "$ASC", email: "*", name: ["$ASC", "$DESC"]],
    overrideable: ["custom_field"]

  @impl true
  def override_sortable("custom_field", "$DESC") do
    {:desc, dynamic([u], fragment("?->>'custom_field'", u.metadata))}
  end

  def override_sortable(_field, _operator), do: nil
end

๐Ÿ“Œ FatEcto.Pagination.Paginator โ€“ Paginate Like a Pro

No more hassle with pagination! FatPaginator helps you paginate Ecto queries efficiently, keeping your APIs snappy and responsive.

Usage of FatPaginator

defmodule Fat.MyPaginator do
  use FatEcto.Pagination.V2Paginator,
    default_limit: 10,
    repo: FatEcto.Repo,
    max_limit: 100
end

๐Ÿš€ Contributing

We love contributions! If youโ€™d like to improve FatEcto, submit an issue or pull request. Letโ€™s build something amazing together! ๐Ÿ”ฅ


๐Ÿ“œ License

FatEcto is released under the MIT License.

๐Ÿ“– See the full documentation at HexDocs for more details.