@spec current_order(t(), atom()) :: order_direction() | nil

Returns the current order direction for the given field.

Examples

iex> flop = %Flop{order_by: [:name, :age], order_directions: [:desc]}
iex> current_order(flop, :name)
:desc
iex> current_order(flop, :age)
:asc
iex> current_order(flop, :species)
nil

@spec map_to_filter_params(
  map(),
  keyword()
) :: [map()]

Converts a map of filter conditions into a list of Flop filter params.

The default operator is :==. nil values are excluded from the result.

iex> params = map_to_filter_params(
...>   %{name: "George", age: 8, species: nil}
...> )
iex> Enum.sort(params)
[
  %{field: :age, op: :==, value: 8},
  %{field: :name, op: :==, value: "George"}
]

iex> params = map_to_filter_params(
...>   %{"name" => "George", "age" => 8, "cat" => true}
...>  )
iex> Enum.sort(params)
[
  %{"field" => "age", "op" => :==, "value" => 8},
  %{"field" => "cat", "op" => :==, "value" => true},
  %{"field" => "name", "op" => :==, "value" => "George"}
]

You can optionally pass a mapping from field names to operators as a map with atom keys.

iex> params = map_to_filter_params(
...>   %{name: "George", age: 8, species: nil},
...>   operators: %{name: :ilike_and}
...> )
iex> Enum.sort(params)
[
  %{field: :age, op: :==, value: 8},
  %{field: :name, op: :ilike_and, value: "George"}
]

iex> map_to_filter_params(
...>   %{"name" => "George", "age" => 8, "cat" => true},
...>   operators: %{name: :ilike_and, age: :<=}
...> )
[
  %{"field" => "age", "op" => :<=, "value" => 8},
  %{"field" => "cat", "op" => :==, "value" => true},
  %{"field" => "name", "op" => :ilike_and, "value" => "George"}
]

You can also pass a map to rename fields.

iex> params = map_to_filter_params(
...>   %{s: "George", age: 8, species: nil},
...>   rename: %{s: :name}
...> )
iex> Enum.sort(params)
[
  %{field: :age, op: :==, value: 8},
  %{field: :name, op: :==, value: "George"}
]

iex> map_to_filter_params(
...>   %{"s" => "George", "cat" => true},
...>   rename: %{s: :name, cat: :dog}
...> )
[
  %{"field" => "dog", "op" => :==, "value" => true},
  %{"field" => "name", "op" => :==, "value" => "George"}
]

If both a rename option and an operator are set for a field, the operator option needs to use the new field name.

iex> map_to_filter_params(
...>   %{n: "George"},
...>   rename: %{n: :name},
...>   operators: %{name: :ilike_or}
...> )
[%{field: :name, op: :ilike_or, value: "George"}]

See also Flop.Filter.new/2.

@spec nest_filters(map(), [atom() | String.t()], keyword()) :: map()

Converts key/value filter parameters at the root of a map, converts them into a list of filter parameter maps and nests them under the :filters key.

This is useful in cases where you get some or all filter parameters as key/value pairs instead of a full map with operators, for example when you expose certain filters with fixed operators on an API, or if you want to reflect some or all filters in the URL as path parameters or simple query parameters (e.g. /posts/{tag} or /posts?s=searchterm).

The given map should have either string keys or atom keys. Passing a map with mixed keys will lead to unexpected results and will cause an Ecto error when the return value is passed to one of the validation functions.

The second argument is a list of fields as atoms.

The opts argument is passed to map_to_filter_params/2.

The function returns a map that eventually needs to be passed to one of the Flop validation functions (any Flop.validate* function) before it can be used to make a query.

Examples

Map with atom keys

iex> nest_filters(%{name: "Peter", page_size: 10}, [:name])
%{filters: [%{field: :name, op: :==, value: "Peter"}], page_size: 10}

Map with string keys

iex> nest_filters(%{"name" => "Peter"}, [:name])
%{"filters" => [%{"field" => "name", "op" => :==, "value" =>  "Peter"}]}

Specifying operators

iex> nest_filters(%{name: "Peter"}, [:name], operators: %{name: :!=})
%{filters: [%{field: :name, op: :!=, value: "Peter"}]}

Renaming fields

iex> nest_filters(%{nombre: "Peter", page_size: 10}, [:nombre],
...>   rename: %{nombre: :name}
...> )
%{filters: [%{field: :name, op: :==, value: "Peter"}], page_size: 10}

iex> nest_filters(%{"nombre" => "Peter"}, [:nombre],
...>   rename: %{nombre: :name}
...> )
%{"filters" => [%{"field" => "name", "op" => :==, "value" =>  "Peter"}]}

iex> nest_filters(%{"nombre" => "Peter"}, [:nombre],
...>   rename: %{nombre: :name},
...>   operators: %{name: :like}
...> )
%{"filters" => [%{"field" => "name", "op" => :like, "value" =>  "Peter"}]}

If the map already has a filters key, the extracted filters are added to the existing filters.

iex> nest_filters(%{name: "Peter", filters: [%{field: "age", op: ">", value: 25}]}, [:name])
%{filters: [%{field: "age", op: ">", value: 25}, %{field: :name, op: :==, value: "Peter"}]}

iex> nest_filters(%{"name" => "Peter", "filters" => [%{"field" => "age", "op" => ">", "value" => 25}]}, [:name])
%{"filters" => [%{"field" => "age", "op" => ">", "value" => 25}, %{"field" => "name", "op" => :==, "value" => "Peter"}]}

If the existing filters are formatted as a map with integer indexes as keys as produced by a form, the map is converted to a list first.

iex> nest_filters(%{name: "Peter", filters: %{"0" => %{field: "age", op: ">", value: 25}}}, [:name])
%{filters: [%{field: "age", op: ">", value: 25}, %{field: :name, op: :==, value: "Peter"}]}

iex> nest_filters(%{"name" => "Peter", "filters" => %{"0" => %{"field" => "age", "op" => ">", "value" => 25}}}, [:name])
%{"filters" => [%{"field" => "age", "op" => ">", "value" => 25}, %{"field" => "name", "op" => :==, "value" => "Peter"}]}

@spec push_order(t(), atom() | String.t(), keyword()) :: t()

Updates the order_by and order_directions values of a Flop struct.

• If the field is not in the current order_by value, it will be prepended to the list. By default, the order direction for the field will be set to :asc.
• If the field is already at the front of the order_by list, the order direction will be reversed.
• If the field is already in the list, but not at the front, it will be moved to the front and the order direction will be set to :asc (or the custom asc direction supplied in the :directions option).
• If the :directions option——a 2-element tuple——is passed, the first and second elements will be used as custom sort declarations for ascending and descending, respectively.

Examples

iex> flop = push_order(%Flop{}, :name)
iex> flop.order_by
[:name]
iex> flop.order_directions
[:asc]
iex> flop = push_order(flop, :age)
iex> flop.order_by
[:age, :name]
iex> flop.order_directions
[:asc, :asc]
iex> flop = push_order(flop, :age)
iex> flop.order_by
[:age, :name]
iex> flop.order_directions
[:desc, :asc]
iex> flop = push_order(flop, :species)
iex> flop.order_by
[:species, :age, :name]
iex> flop.order_directions
[:asc, :desc, :asc]
iex> flop = push_order(flop, :age)
iex> flop.order_by
[:age, :species, :name]
iex> flop.order_directions
[:asc, :asc, :asc]

By default, the function toggles between :asc and :desc. You can override this with the :directions option.

iex> directions = {:asc_nulls_last, :desc_nulls_last}
iex> flop = push_order(%Flop{}, :ttfb, directions: directions)
iex> flop.order_by
[:ttfb]
iex> flop.order_directions
[:asc_nulls_last]
iex> flop = push_order(flop, :ttfb, directions: directions)
iex> flop.order_by
[:ttfb]
iex> flop.order_directions
[:desc_nulls_last]

This also allows you to sort in descending order initially.

iex> directions = {:desc, :asc}
iex> flop = push_order(%Flop{}, :ttfb, directions: directions)
iex> flop.order_by
[:ttfb]
iex> flop.order_directions
[:desc]
iex> flop = push_order(flop, :ttfb, directions: directions)
iex> flop.order_by
[:ttfb]
iex> flop.order_directions
[: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

Since the pagination cursor depends on the sort order, the :before and :after parameters are reset.

iex> push_order(%Flop{order_by: [:id], after: "ABC"}, :name)
%Flop{order_by: [:name, :id], order_directions: [:asc], after: nil}
iex> push_order(%Flop{order_by: [:id], before: "DEF"}, :name)
%Flop{order_by: [:name, :id], order_directions: [:asc], before: nil}

@spec reset_cursors(t()) :: t()

Removes the after and before cursors from a Flop struct.

Example

iex> reset_cursors(%Flop{after: "A"})
%Flop{}

iex> reset_cursors(%Flop{before: "A"})
%Flop{}

@spec reset_filters(t()) :: t()

Removes all filters from a Flop struct.

Example

iex> reset_filters(%Flop{filters: [
...>   %Flop.Filter{field: :name, value: "Jim"}
...> ]})
%Flop{filters: []}

@spec reset_order(t()) :: t()

Removes the order parameters from a Flop struct.

Example

iex> reset_order(%Flop{order_by: [:name], order_directions: [:asc]})
%Flop{order_by: nil, order_directions: nil}

@spec set_cursor(Flop.Meta.t(), :previous | :next) :: t()

Takes a Flop.Meta struct and returns a Flop struct with updated cursor pagination params for going to either the previous or the next page.

See to_previous_cursor/1 and to_next_cursor/1 for details.

Examples

iex> set_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_previous_page?: true, start_cursor: "b"
...>   },
...>   :previous
...> )
%Flop{last: 5, before: "b"}

iex> set_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_next_page?: true, end_cursor: "b"
...>   },
...>   :next
...> )
%Flop{first: 5, after: "b"}

@spec set_offset(t(), non_neg_integer() | binary()) :: t()

Sets the offset value of a Flop struct while also removing/converting pagination parameters for other pagination types.

iex> set_offset(%Flop{limit: 10, offset: 10}, 20)
%Flop{offset: 20, limit: 10}

iex> set_offset(%Flop{page: 5, page_size: 10}, 20)
%Flop{limit: 10, offset: 20, page: nil, page_size: nil}

iex> set_offset(%Flop{limit: 10, offset: 10}, "20")
%Flop{offset: 20, limit: 10}

The offset will not be allowed to go below 0.

iex> set_offset(%Flop{}, -5)
%Flop{offset: 0}

@spec set_page(t(), pos_integer() | binary()) :: t()

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}

iex> set_page(%Flop{page: 2, page_size: 10}, "6")
%Flop{page: 6, page_size: 10}

The page number will not be allowed to go below 1.

iex> set_page(%Flop{}, -5)
%Flop{page: 1}

@spec to_next_cursor(Flop.Meta.t()) :: t()

Takes a Flop.Meta struct and returns a Flop struct with updated cursor pagination params for going to the next page.

Examples

iex> to_next_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_next_page?: true, end_cursor: "b"
...>   }
...> )
%Flop{first: 5, after: "b"}

iex> to_next_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{last: 5, before: "b"},
...>     has_next_page?: true, end_cursor: "a"
...>   }
...> )
%Flop{first: 5, after: "a"}

If there is no next page, the Flop struct is returned unchanged.

iex> to_next_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_next_page?: false, start_cursor: "b"
...>   }
...> )
%Flop{first: 5, after: "a"}

It can happen that has_next_page? is true, but no end cursor is set, for example if the user is on the second page and switches to the previous page right after the only item on the first page is deleted. Since the result set is empty and there is no end cursor in this case, this function sets the new after parameter to nil. By doing this, the user is sent to the first page without skipping any items.

iex> to_next_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_next_page?: true, end_cursor: nil
...>   }
...> )
%Flop{first: 5, after: nil}

iex> to_next_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{last: 5, before: "b"},
...>     has_next_page?: true, end_cursor: nil
...>   }
...> )
%Flop{first: 5, after: nil}

@spec to_next_offset(t(), non_neg_integer() | nil) :: t()

Sets the offset of a Flop struct to the next page depending on the limit.

If the total count is given as the second argument, the offset will not be increased if the last page has already been reached. You can get the total count from the Flop.Meta struct. If the Flop has an offset beyond the total count, the offset will be set to the last page.

Examples

iex> to_next_offset(%Flop{offset: 10, limit: 5})
%Flop{offset: 15, limit: 5}

iex> to_next_offset(%Flop{offset: 15, limit: 5}, 21)
%Flop{offset: 20, limit: 5}

iex> to_next_offset(%Flop{offset: 15, limit: 5}, 20)
%Flop{offset: 15, limit: 5}

iex> to_next_offset(%Flop{offset: 28, limit: 5}, 22)
%Flop{offset: 20, limit: 5}

iex> to_next_offset(%Flop{offset: -5, limit: 20})
%Flop{offset: 0, limit: 20}

@spec to_next_page(t(), non_neg_integer() | nil) :: t()

Sets the page of a Flop struct to the next page.

If the total number of pages is given as the second argument, the page number will not be increased if the last page has already been reached. You can get the total number of pages from the Flop.Meta struct.

Examples

iex> to_next_page(%Flop{page: 5})
%Flop{page: 6}

iex> to_next_page(%Flop{page: 5}, 6)
%Flop{page: 6}

iex> to_next_page(%Flop{page: 6}, 6)
%Flop{page: 6}

iex> to_next_page(%Flop{page: 7}, 6)
%Flop{page: 6}

iex> to_next_page(%Flop{page: -5})
%Flop{page: 1}

@spec to_previous_cursor(Flop.Meta.t()) :: t()

Takes a Flop.Meta struct and returns a Flop struct with updated cursor pagination params for going to the previous page.

Examples

iex> to_previous_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_previous_page?: true, start_cursor: "b"
...>   }
...> )
%Flop{last: 5, before: "b"}

iex> to_previous_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{last: 5, before: "b"},
...>     has_previous_page?: true, start_cursor: "a"
...>   }
...> )
%Flop{last: 5, before: "a"}

If there is no previous page, the Flop struct is returned unchanged.

iex> to_previous_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "b"},
...>     has_previous_page?: false, start_cursor: "a"
...>   }
...> )
%Flop{first: 5, after: "b"}

It can happen that has_previous_page? is true, but no start cursor is set, for example if the user is on the next-to-last page and switches to the next page right after the only item on the last page is deleted. Since the result set would be empty and there is no start cursor in this case, this function sets the new before parameter to nil. By doing this, the user is sent to the actual last page without skipping any items.

iex> to_previous_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{first: 5, after: "a"},
...>     has_previous_page?: true, start_cursor: nil
...>   }
...> )
%Flop{last: 5, before: nil}

iex> to_previous_cursor(
...>   %Flop.Meta{
...>     flop: %Flop{last: 5, before: "b"},
...>     has_previous_page?: true, start_cursor: nil
...>   }
...> )
%Flop{last: 5, before: nil}