Merge pull request #123 from woylie/helper-functions

Helper functions

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+## [0.12.0] - 2021-08-11
+
 ### Added
 
 - Allow to define join fields in `Flop.Schema`.
@@ -10,12 +12,14 @@
 - Support filtering by compound fields.
 - New filter operator `empty`.
 - New filter operator `not_empty`.
+- New function `Flop.set_page/2`.
 
 ### Changed
 
 - Rename option `get_cursor_value_func` to `cursor_value_func`.
 - Silently ignore filters with `nil` value for the field or the value instead of
   raising an `ArgumentError`.
+- Allow passing a string as the second argument to `Flop.push_order/2`.
 
 ## [0.11.0] - 2021-06-13
 

README.md

@@ -31,7 +31,7 @@ Add `flop` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:flop, "~> 0.11.0"}
+    {:flop, "~> 0.12.0"}
   ]
 end
 ```

lib/flop.ex

@@ -1087,6 +1087,37 @@ defmodule Flop do
     end
   end
 
+  @doc """
+  Sets the page value of a `Flop` struct while also removing/converting
+  pagination parameters for other pagination types.
+
+      iex> set_page(%Flop{page: 2, page_size: 10}, 6)
+      %Flop{page: 6, page_size: 10}
+
+      iex> set_page(%Flop{limit: 10, offset: 20}, 8)
+      %Flop{limit: nil, offset: nil, page: 8, page_size: 10}
+
+  The page number will not be allowed to go below 1.
+
+      iex> set_page(%Flop{}, -5)
+      %Flop{page: 1}
+  """
+  @doc since: "0.12.0"
+  @spec set_page(Flop.t(), pos_integer) :: Flop.t()
+  def set_page(%Flop{} = flop, page) do
+    %{
+      flop
+      | after: nil,
+        before: nil,
+        first: nil,
+        last: nil,
+        limit: nil,
+        offset: nil,
+        page_size: flop.page_size || flop.limit || flop.first || flop.last,
+        page: max(page, 1)
+    }
+  end
+
   @doc """
   Updates the `order_by` and `order_directions` values of a `Flop` struct.
 
@@ -1124,8 +1155,19 @@ defmodule Flop do
       [:age, :species, :name]
       iex> flop.order_directions
       [:asc, :asc, :asc]
+
+  If a string is passed as the second argument, it will be converted to an atom
+  using `String.to_existing_atom/1`. If the atom does not exist, the `Flop`
+  struct will be returned unchanged.
+
+      iex> flop = push_order(%Flop{}, "name")
+      iex> flop.order_by
+      [:name]
+      iex> flop = push_order(%Flop{}, "this_atom_does_not_exist")
+      iex> flop.order_by
+      nil
   """
-  @spec push_order(Flop.t(), atom) :: Flop.t()
+  @spec push_order(Flop.t(), atom | String.t()) :: Flop.t()
   @doc since: "0.10.0"
   def push_order(
         %Flop{order_by: order_by, order_directions: order_directions} = flop,
@@ -1148,6 +1190,12 @@ defmodule Flop do
     %{flop | order_by: order_by, order_directions: order_directions}
   end
 
+  def push_order(flop, field) when is_binary(field) do
+    push_order(flop, String.to_existing_atom(field))
+  rescue
+    _e in ArgumentError -> flop
+  end
+
   defp get_index(nil, _field), do: nil
   defp get_index(order_by, field), do: Enum.find_index(order_by, &(&1 == field))
 

lib/flop/schema.ex

@@ -157,6 +157,9 @@ defprotocol Flop.Schema do
 
   If you need filter or order across tables, you can define join fields.
 
+  **Note: Support for ordering by join fields will be added in a future
+  version.**
+
   As an example, let's define these schemas:
 
       schema "owners" do

mix.exs

@@ -2,7 +2,7 @@ defmodule Flop.MixProject do
   use Mix.Project
 
   @source_url "https://github.com/woylie/flop"
-  @version "0.11.0"
+  @version "0.12.0"
 
   def project do
     [